Finish 1.0.0

heuer · Feb 13, 2020 · 7d71ef1 · 7d71ef1
2 parents 78866b2 + 45c27cc
commit 7d71ef1
Show file tree

Hide file tree

Showing 58 changed files with 838 additions and 538 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,6 +1,25 @@
 Changes
 =======
 
+Versions follow `Semantic Versioning <https://semver.org/>`_.
+
+1.0.0 -- 2020-02-14
+-------------------
+* Removed support for ``color`` / ``background`` keywords (deprecated in 0.4.0).
+  Use ``dark`` and ``light``.
+* Reintroduced ``segno.DataOverflowError`` (inherited from ``ValueError``) to
+  indicate that the provided data does not fit into the provided (Micro) QR Code
+  parameters.
+* Documentation improvements
+* Although this lib made backwards incompatible changes since version 0.1.0,
+  the changes should be clear since almost all changes were made
+  very conservative with background compatibility in mind.
+  Even early adopters should find a clear update path.
+  This version marks a stable API acc. to `Semantic Versioning <https://semver.org/>`_.
+* The initial stable release after nearly four years of development. Happy
+  valentine ;)
+
+
 0.4.0 -- 2020-01-21
 -------------------
 * Removed deprecated functions, modules etc. See #56, #57, #59, #61, #67.

diff --git a/README.rst b/README.rst
@@ -135,7 +135,7 @@ Micro QR Codes (or raises an error if the content is too large for a Micro QR Co
     >>> mqr = segno.make_micro('Nick Cave and the Bad Seeds')
     Traceback (most recent call last):
         ...
-    ValueError: Data too large. No Micro QR Code can handle the provided data
+    DataOverflowError: Data too large. No Micro QR Code can handle the provided data
 
 
 All factory functions use the same parameters to specify the desired error

diff --git a/docs/_static/chart_create_1m.svg b/docs/_static/chart_create_1m.svg
diff --git a/docs/_static/chart_create_30h.svg b/docs/_static/chart_create_30h.svg
diff --git a/docs/_static/chart_create_7q.svg b/docs/_static/chart_create_7q.svg
diff --git a/docs/_static/chart_png.svg b/docs/_static/chart_png.svg
diff --git a/docs/_static/chart_svg.svg b/docs/_static/chart_svg.svg
diff --git a/docs/_static/light-my-fire-1-m.png b/docs/_static/light-my-fire-1-m.png
diff --git a/docs/_static/light-my-fire-m4-m.png b/docs/_static/light-my-fire-m4-m.png
diff --git a/docs/_static/parisienne_walkways-2-l.png b/docs/_static/parisienne_walkways-2-l.png
diff --git a/docs/_static/parisienne_walkways-2-q.png b/docs/_static/parisienne_walkways-2-q.png
diff --git a/docs/_static/parisienne_walkways-3-h.png b/docs/_static/parisienne_walkways-3-h.png
diff --git a/docs/_static/paul-mccartney.svg b/docs/_static/paul-mccartney.svg
diff --git a/docs/_static/rain-1-h.png b/docs/_static/rain-1-h.png
diff --git a/docs/_static/rain-m3-m.png b/docs/_static/rain-m3-m.png
diff --git a/docs/_static/sgt-peppers-dark_0000ffcc.png b/docs/_static/sgt-peppers-dark_0000ffcc.png
diff --git a/docs/_static/sgt-peppers-dark_00fc.svg b/docs/_static/sgt-peppers-dark_00fc.svg
diff --git a/docs/_static/sgt-peppers-dark_685e5c.svg b/docs/_static/sgt-peppers-dark_685e5c.svg
diff --git a/docs/_static/sgt-peppers-dark_890117.svg b/docs/_static/sgt-peppers-dark_890117.svg
diff --git a/docs/_static/sgt-peppers-dark_darkred-light_lightblue.svg b/docs/_static/sgt-peppers-dark_darkred-light_lightblue.svg
diff --git a/docs/_static/sgt-peppers-dark_transparent-light_black.png b/docs/_static/sgt-peppers-dark_transparent-light_black.png
diff --git a/docs/_static/sgt-peppers-light_transparent.png b/docs/_static/sgt-peppers-light_transparent.png
diff --git a/docs/_static/the-beatles-1-q-scale-1-unit-cm.svg b/docs/_static/the-beatles-1-q-scale-1-unit-cm.svg
diff --git a/docs/_static/the-beatles-1-q-scale-1.png b/docs/_static/the-beatles-1-q-scale-1.png
diff --git a/docs/_static/the-beatles-1-q-scale-10-unit-mm.svg b/docs/_static/the-beatles-1-q-scale-10-unit-mm.svg
diff --git a/docs/_static/the-beatles-1-q-scale-10.png b/docs/_static/the-beatles-1-q-scale-10.png
diff --git a/docs/_static/the-beatles-1-q-scale-2.4.svg b/docs/_static/the-beatles-1-q-scale-2.4.svg
diff --git a/docs/_static/the-beatles-1-q.png b/docs/_static/the-beatles-1-q.png
diff --git a/docs/_static/the-beatles-m4-m.png b/docs/_static/the-beatles-m4-m.png
diff --git a/docs/_static/the-beatles.png b/docs/_static/the-beatles.png
diff --git a/docs/_static/tomorrow-never-knows-2-q.png b/docs/_static/tomorrow-never-knows-2-q.png
diff --git a/docs/_static/vampire-blues-m4-m-border-10.png b/docs/_static/vampire-blues-m4-m-border-10.png
diff --git a/docs/_static/vampire-blues-m4-m-no-border.svg b/docs/_static/vampire-blues-m4-m-no-border.svg
diff --git a/docs/command-line.rst b/docs/command-line.rst
@@ -164,15 +164,16 @@ Usually, all QR Codes are serialized in black and white. Use
 :option:`--dark <segno --dark>` to change the color of the dark modules and
 :option:`--light <segno --light>` to change the color of the light modules.
 
-Change the foreground color to darkblue::
+Change the color of the dark modules to to darkblue::
 
     $ segno --dark=darkblue --scale 4 --output=excited.png "So Excited"
 
 .. image:: _static/cli/excited.png
     :alt: QR Code "So Excited" with foreground color "darkblue"
 
 
-Change the background color to transparent::
+
+Change the color of the light modules to transparent::
 
     $ segno --light=transparent --scale 4 --output=hotel.png "Hotel California"
 
@@ -192,8 +193,11 @@ modules to yellow::
 If the serializer does not support :option:`--color <segno --dark>` or
 :option:`--light <segno --light>`, these arguments are ignored.
 
-The PNG serializer supports more than two colors, each module type (finder pattern
-(dark / light), alignment pattern (dark / light) etc.) may have its own color::
+The SVG and PNG serializers support more than two colors, each module type
+(finder pattern (dark / light), alignment pattern (dark / light) etc.) may have
+its own color, see :doc:`colorful-qrcodes` for details.
+
+.. code-block:: bash
 
     $ segno --dark darkred --data-dark darkorange --data-light yellow --scale 5 -o yellow-submarine.png Yellow Submarine
 

diff --git a/docs/epc-qrcodes.rst b/docs/epc-qrcodes.rst
@@ -1,7 +1,7 @@
 EPC QR Codes
 ============
 
-European Payments Council Quick Response Code (EPC QR Codes) are used to
+European Payments Council Quick Response Codes (EPC QR Codes) are used to
 initiate SEPA credit transfers. They encode all necessary data (IBAN, amount,
 recipient) and may be placed on invoices to eliminate the error-prone typing
 of payment Information.

diff --git a/docs/make.rst b/docs/make.rst
@@ -15,10 +15,11 @@ or Micro QR Code:
     >>> qr.save('henry-lee.txt')  # Text output
 
 
-By default, the serialized (Micro) QR Codes are black and have a quiet zone
-(border) of four (or two for Micro QR Codes) light modules. Nearly all output
-formats provide options to change at least the scale of the code, the color,
-and border, see :py:func:`segno.QRCode.save()` and :doc:`serializers` for details.
+By default, the serialized (Micro) QR Codes are black and white (or transparent)
+and have a quiet zone (border) of four (or two for Micro QR Codes) light modules.
+Nearly all output formats provide options to change at least the scale of the
+code, the color of the dark modules, and the border, see
+:py:func:`segno.QRCode.save()` and :doc:`serializers` for details.
 
 .. code-block:: python
 
@@ -40,6 +41,10 @@ version with a maximal error correction for the provided input.
     'M3'
 
 
+.. image:: _static/rain-m3-m.png
+    :alt: "M3-M Micro QR Code encoding 'Rain'"
+
+
 The caller may enforce that a QR Code instead of a Micro QR Code should be
 generated even if the content may fit into a Micro QR Code.
 
@@ -51,6 +56,10 @@ generated even if the content may fit into a Micro QR Code.
     1
 
 
+.. image:: _static/rain-1-h.png
+    :alt: "1-H QR Code encoding 'Rain'"
+
+
 Further, Segno provides two additional factory functions to enforce the creation
 of QR Codes or Micro QR Codes: :py:func:`segno.make_qr` for QR Codes and
 :py:func:`segno.make_micro` to create Micro QR Codes:
@@ -61,15 +70,35 @@ of QR Codes or Micro QR Codes: :py:func:`segno.make_qr` for QR Codes and
     >>> mqr = segno.make_micro('The Beatles')  # Micro QR Code
     >>> mqr.designator  # Get the version and error level
     'M4-M'
+
+.. image:: _static/the-beatles-m4-m.png
+    :alt: "M4-M Micro QR Code encoding 'The Beatles'"
+
+
+.. code-block:: python
+
+    >>> import segno
     >>> qr = segno.make_qr('The Beatles')  # Same content but as QR Code
     >>> qr.designator
     '1-Q'
+
+.. image:: _static/the-beatles-1-q.png
+    :alt: "1-Q QR Code encoding 'The Beatles'"
+
+
+.. code-block:: python
+
+    >>> import segno
     >>> qr = segno.make('The Beatles', micro=False)  # Disallow Micro QR Codes
     >>> qr.designator
     '1-Q'
 
+.. image:: _static/the-beatles-1-q.png
+    :alt: "1-Q QR Code encoding 'The Beatles'"
+
 
-If the provided content is too large, a :py:exc:`ValueError` is thrown:
+If the provided content is too large, a :py:exc:`segno.DataOverflowError` is
+thrown:
 
 
 .. code-block:: python
@@ -78,7 +107,7 @@ If the provided content is too large, a :py:exc:`ValueError` is thrown:
     >>> qr = segno.make_micro('The Curse of Millhaven')
     Traceback (most recent call last):
         ...
-    ValueError: Data too large. No Micro QR Code can handle the provided data
+    DataOverflowError: Data too large. No Micro QR Code can handle the provided data
 
 
 
@@ -95,12 +124,23 @@ It's possible to specify the desired version for the provided ``content``.
     'M4'
     >>> qr.designator
     'M4-M'
+
+.. image:: _static/light-my-fire-m4-m.png
+    :alt: "M4-M QR Code encoding 'Light My fire'"
+
+
+.. code-block:: python
+
+    >>> import segno
     >>> qr = segno.make('Light My Fire', version=1)
     >>> qr.version
     1
     >>> qr.designator
     '1-M'
 
+.. image:: _static/light-my-fire-1-m.png
+    :alt: "1-M QR Code encoding 'Light My fire'"
+
 
 Error Correction Level
 ----------------------
@@ -109,7 +149,7 @@ By default, Segno uses at minimum the error correction level "L" to encode
 the (Micro) QR Code.
 
 Segno tries by default to enhance the provided error correction level if
-:paramref:`boost_error <segno.make.boost_error>` was not set to ``False``;
+:paramref:`boost_error <segno.make.boost_error>` is not set to ``False``;
 it takes  the ``error`` level as minimum error level without changing the
 (Micro) QR Code version.
 
@@ -120,25 +160,48 @@ Use the parameter :paramref:`error <segno.make.error>` to change the (minimum)
 error correction level.
 
 The `error` parameter is case-insensitive. Available error correction levels are
-``L`` (lowest error correction level), ``M``, ``Q`` and ``H`` (highest error
-correction level). The error correction level "H" is not available for Micro QR Codes,
-if the user specifies the error correction level "H", a QR Code is generated by
-:py:func:`segno.make`, never a Micro QR Code.
+``L`` (lowest error correction level: 7% of codewords can be restored), ``M``
+(error correction level "medium": 15% of codewords can be restored), ``Q``
+(error correction level "quartile": 25% of codewords can be restored),  and ``H``
+(highest error correction level: 30% of codewords can be restored). The error
+correction level "H" is not available for Micro QR Codes, if the user specifies
+the error correction level "H", a QR Code is generated by :py:func:`segno.make`,
+never a Micro QR Code.
 
 .. code-block:: python
 
     >>> import segno
     >>> qr = segno.make('Parisienne Walkways', error='l')  # Explicit (minimum) error correction level
     >>> qr.designator # The error correction level was changed to "Q" since there was enough available space
     '2-Q'
+
+
+.. image:: _static/parisienne_walkways-2-q.png
+    :alt: "2-Q QR Code encoding 'Parisienne Walkways'"
+
+.. code-block:: python
+
+    >>> import segno
     >>> qr = segno.make('Parisienne Walkways', error='l', boost_error=False)  # Explicit error level
     >>> qr.designator
     '2-L'
+
+
+.. image:: _static/parisienne_walkways-2-l.png
+    :alt: "2-L QR Code encoding 'Parisienne Walkways'"
+
+
+.. code-block:: python
+
+    >>> import segno
     >>> # Enhancing the error correction level may enforce another QR Code version
     >>> qr = segno.make('Parisienne Walkways', error='H')
     >>> qr.designator
     '3-H'
 
+.. image:: _static/parisienne_walkways-3-h.png
+    :alt: "3-H QR Code encoding 'Parisienne Walkways'"
+
 
 Data Masking
 ------------