Release 0.3.6

CHANGES.rst

@@ -1,13 +1,51 @@
 Changes
 =======
 
+0.3.6 -- 2020-01-06
+-------------------
+* Backwards incompatibility change: QRCode.show() uses "dark" instead of
+  "color" and "light" instead of "background" to define the color of
+  the dark / light modules
+* Backwards incompatibility change: All ``segno.writers`` use "dark" instead of
+  "color" and "light" instead of "background". This does not affect normal users,
+  but only users of the low level API.
+* Changed the keyword for setting the color of the dark modules from
+  "color" to "dark" and for setting the light modules from "background"
+  to "light"
+  The former keywords are still supported. Their usage will issue a
+  DeprecationWarning in the future.
+* Added ``--dark`` and ``--light`` to the command line interface, see point
+  above. ```--color``` and ``--background`` are still supported.
+* Fixed typos, improved documentation
+* Deprecated ``segno.moduletypes`` (will be removed in release 0.4.0),
+  moved all constants to ``segno.consts``
+* Deprecated usage of parameter "colormap" (introduced in 0.3.4). It still
+  works but a deprecation warning is issued.
+  Instead of::
+
+      colormap = {mt.TYPE_FINDER_PATTERN_DARK: 'darkred',
+                  mt.TYPE_ALIGNMENT_PATTERN_DARK: 'darkred',
+                  mt.TYPE_TIMING_DARK: 'darkred',
+                  mt.TYPE_DARKMODULE: 'darkred',
+                  mt.TYPE_DATA_DARK: 'darkorange',
+                  mt.TYPE_DATA_LIGHT: 'yellow',
+                  mt.TYPE_FORMAT_DARK: 'darkred'}
+
+      qr.save('qrcode.png', scale=5, colormap=colormap)
+
+  use::
+
+      qr.save('qrcode.png', scale=5, dark='darkred', data_dark='darkorange',
+              data_light='yellow')
+
+
 0.3.5 -- 2020-01-03
 -------------------
 * Added support for colorful (more than two colors) QR Codes to the CLI script
   (fixes #58).
 * Fixed Read the Docs build
 * Improved documentation
-* Minor perfomance and code improvements.
+* Minor performance and code improvements.
 
 
 0.3.4 -- 2020-01-02
@@ -39,9 +77,10 @@ Changes
 * Fixed bugs in ``helpers.make_vcard_data`` function
   (superfluous semicolon in birthday line, check geo coordinates)
 * Renamed ``utils.matrix_iter_detail`` into ``utils.matrix_iter_verbose``.
-  Kept ``matrix_iter_detail`` for backwards compatibility (deprecated)
+  Kept ``matrix_iter_detail`` for backwards compatibility (deprecated, will be
+  removed in release 0.4.0)
 * Moved module constants from ``segno.utils`` into ``segno.moduletypes``,
-  Constants from ``segno.utils`` will be removed within the next release.
+  Constants from ``segno.utils`` will be removed in release 0.4.0.
 * Added option ``verbose`` (default: ``False``) to ``segno.QRCode.matrix_iter()``
   which returns an iterator which provides information about the module type
   (i.e. quiet zone, dark data module, light data module).

README.rst

@@ -64,8 +64,8 @@ The command line script prints the QR Code to the terminal::
 To serialize the QR Code, use the "output" argument::
 
     $ segno -o=raincoat.svg "Famous Blue Raincoat"
-    $ segno --scale=10 --color=darkblue --border=0 --output=fire.svg "Who by Fire"
-    $ segno --scale=10 --background=transparent --output=miracle.png "Waiting for the Miracle"
+    $ segno --scale 10 --dark darkblue --border 0 --output=fire.svg "Who by Fire"
+    $ segno --scale 10 --light transparent --output=miracle.png "Waiting for the Miracle"
 
 
 
@@ -78,15 +78,11 @@ Library
     >>> # Let Segno choose the minimal version and an optimal (maximal) error
     >>> # level without changing the minimal version
     >>> qr = segno.make('Up Jumped the Devil')
-    >>> qr.is_micro
-    False
-    >>> qr.version
-    2
-    >>> qr.error
-    'Q'
+    >>> qr.designator  # Returns the QR Code version and the error correction level
+    '2-Q'
     >>> qr.save('up-jumped-the-devil.png')  # Save as PNG
     >>> qr.save('up-jumped-the-devil-2.png', scale=10)  # Scaling factor 10
-    >>> qr.save('up-jumped-the-devil-3.png', background=None)  # Transparent background
+    >>> qr.save('up-jumped-the-devil-3.png', light=None)  # Transparent light modules
     >>> qr.save('up-jumped-the-devil.pdf', scale=10)  # Save as PDF
     >>> # SVG drawing the dark modules in "dark blue"
     >>> qr.save('up-jumped-the-devil.svg', scale=10, color='darkblue')
@@ -100,24 +96,35 @@ If the content to encode is small enough, a Micro QR Code is generated:
     >>> qr = segno.make('RAIN')
     >>> qr.is_micro
     True
-    >>> qr.version
-    'M2'
+    >>> qr.designator
+    'M2-M'
+
+
+If this behaviour is not desired, the user may set ``micro`` to ``False``
+
+.. code-block:: python
+
+    >>> import segno
+    >>> qr = segno.make('RAIN', micro=False)
+    >>> qr.is_micro
+    False
+    >>> qr.designator
+    '1-H'
 
 
-If this behaviour is not desired, the user may use the factory functions
-``segno.make_qr()`` which generates always QR Codes (never Micro QR Codes) or
-``segno.make_micro()`` which generates always Micro QR Codes (or raises an error
-if the content is too large for a Micro QR Code).
+Or use the factory functions ``segno.make_qr()`` which generates always QR Codes
+(never Micro QR Codes) or ``segno.make_micro()`` which returns always
+Micro QR Codes (or raises an error if the content is too large for a Micro QR Code).
 
 .. code-block:: python
 
     >>> import segno
     >>> mqr = segno.make_micro('THE BEATLES')
-    >>> mqr.version
-    'M3'
+    >>> mqr.designator
+    'M3-M'
     >>> qr = segno.make_qr('THE BEATLES')  # Same content but enforce a QR Code
-    >>> qr.version
-    1
+    >>> qr.designator
+    '1-Q'
     >>> # This won't work since the data does not fit into a Micro QR Code M1 - M4
     >>> mqr = segno.make_micro('Nick Cave and the Bad Seeds')
     Traceback (most recent call last):

docs/api-low-level.rst

@@ -27,3 +27,10 @@ segno.writers
 
 .. automodule:: segno.writers
     :members:
+
+
+segno.utils
+-----------
+
+.. automodule:: segno.utils
+    :members:

docs/api.rst

@@ -1,5 +1,5 @@
-Segno package
-=============
+API
+===
 
 Module contents
 ---------------
@@ -9,20 +9,6 @@ Module contents
     :members:
 
 
-Utilities
----------
-
-.. automodule:: segno.utils
-    :members:
-
-
-Module Types
-------------
-
-.. automodule:: segno.moduletypes
-    :members:
-
-
 High level QR Code factories
 ----------------------------
 

docs/command-line.rst

@@ -173,42 +173,42 @@ Colors
 ------
 
 Usually, all QR Codes are serialized in black and white. Use
-:option:`--color <segno --color>` to change the color of the dark modules and
-:option:`--background <segno --background>` to change the color of the light modules.
+: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::
 
-    $ segno --color=darkblue --output=excited.png "So Excited"
+    $ segno --dark=darkblue --output=excited.png "So Excited"
 
 .. image:: _static/excited.png
     :alt: QR Code "So Excited" with foreground color "darkblue"
 
 
 Change the background color to transparent::
 
-    $ segno --background=transparent --output=hotel.png "Hotel California"
+    $ segno --light=transparent --output=hotel.png "Hotel California"
 
 .. image:: _static/hotel.png
     :alt: QR Code "Hotel California" with background color "transparent"
 
 
 Change the foreground color to darkblue and background to yellow::
 
-    $ segno --color=darkblue --background=yellow --output=dontgiveup.svg "Don't Give Up"
+    $ segno --dark=darkblue --light=yellow --output=dontgiveup.svg "Don't Give Up"
 
 .. image:: _static/dontgiveup.svg
     :alt: QR Code "Don't Give Up" with foreground color "transparent"
 
 
-If the serializer does not support :option:`--color <segno --color>` or
-:option:`--background <segno --background>`, these arguments are ignored.
+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::
 
-    $ segno --finder-dark darkred --format-dark darkred --version-dark darkred --data-dark darkorange --data-light yellow --timing-dark darkred --dark-module darkred --scale 5 -o yellow-submarine.png Yellow Submarine
+    $ segno --dark darkred --data-dark darkorange --data-light yellow --scale 5 -o yellow-submarine.png Yellow Submarine
 
-.. image:: _static/cli_yellow-submarine.png
+.. image:: _static/yellow-submarine.png
     :alt: QR Code "Yellow Submarine" colorful
 
 

docs/comparison-qrcode-libs.rst

@@ -69,7 +69,7 @@ Features
 Performance
 -----------
 
-Some performance indicators. The script `benchmarks.py`_ ran on a
+Some performance indicators. The script `benchmarks.py`_ ran on
 Intel i7-8559U / CPython 3.7. Each SVG / PNG image uses a
 scaling factor of 10 (aside from qrcodegen which does not support any scaling).
 

docs/index.rst

@@ -23,7 +23,6 @@ Contents:
     epc-qrcodes
     comparison-qrcode-libs
     man/index
-    replace-qrcode-libs
     plugins
     api
     api-low-level

docs/make.rst

@@ -25,8 +25,8 @@ and border, see :py:func:`segno.QRCode.save()` and :doc:`serializers` for detail
     >>> import segno
     >>> qr = segno.make('You Know My Name (Look Up The Number)')
     >>> qr.save('you-know-my-name-no-border.svg', border=0)  # no border / quiet zone
-    >>> qr.save('you-know-my-name-color-green.svg', color='green')  # default border, dark modules are green
-    >>> qr.save('you-know-my-name-background-grey.svg', background='#eee')  # default border, background grey
+    >>> qr.save('you-know-my-name-color-green.svg', dark='green')  # default border, dark modules are green
+    >>> qr.save('you-know-my-name-background-grey.svg', light='#eee')  # default border, background grey
 
 
 The factory function :py:func:`segno.make` chooses the minimal possible (Micro) QR Code

docs/man/segno.rst

@@ -91,17 +91,17 @@ Command Line Options
     By default, the standard border (4 modules for QR Codes, 2 modules for
     Micro QR Codes) will be used. A value of 0 omits the border
 
-.. option:: --color COLOR
+.. option:: --dark COLOR
 
     Color of the dark modules. The color may be specified as web color name,
     i.e. "red" or as hexadecimal value, i.e. "#0033cc". Some serializers, i.e.
     SVG and PNG, support alpha channels (8-digit hexadecimal value) and
     some support "transparent" as color value. The standard color is black.
 
-.. option:: --background BACKGROUND, -bg BACKGROUND
+.. option:: --light COLOR
 
     Color of the light modules.
-    See :option:`--color` for a description of allowed values.
+    See :option:`--dark` for a description of allowed values.
     The standard background color is white.
 
 .. option:: --output OUTPUT, -o OUTPUT
@@ -174,77 +174,77 @@ Command Line Options
 .. option:: --finder-dark COLOR
 
     Sets the color of the dark modules of the finder pattern.
-    See :option:`--color` for a description of allowed values.
+    See :option:`--dark` for a description of allowed values.
 
 .. option:: --finder-light COLOR
 
     Sets the color of the light modules of the finder pattern.
-    See :option:`--color` for a description of allowed values.
+    See :option:`--dark` for a description of allowed values.
 
 .. option:: --separator COLOR
 
     Sets the color of the separator.
-    See :option:`--color` for a description of allowed values.
+    See :option:`--dark` for a description of allowed values.
 
 .. option:: --data-dark COLOR
 
     Sets the color of the dark data modules.
-    See :option:`--color` for a description of allowed values.
+    See :option:`--dark` for a description of allowed values.
 
 .. option:: --data-light COLOR
 
     Sets the color of the light data modules.
-    See :option:`--color` for a description of allowed values.
+    See :option:`--dark` for a description of allowed values.
 
 .. option:: --quiet-zone COLOR
 
     Sets the color of the quiet zone (border).
-    See :option:`--color` for a description of allowed values.
+    See :option:`--dark` for a description of allowed values.
 
 .. option:: --align-dark COLOR
 
     Sets the color of the dark modules of the alignment patterns.
-    See :option:`--color` for a description of allowed values.
+    See :option:`--dark` for a description of allowed values.
 
 .. option:: --align-light COLOR
 
     Sets the color of the light modules of the alignment patterns.
-    See :option:`--color` for a description of allowed values.
+    See :option:`--dark` for a description of allowed values.
 
 .. option:: --timing-dark COLOR
 
     Sets the color of the dark modules of the timing pattern.
-    See :option:`--color` for a description of allowed values.
+    See :option:`--dark` for a description of allowed values.
 
 .. option:: --timing-light COLOR
 
     Sets the color of the light modules of the timing pattern.
-    See :option:`--color` for a description of allowed values.
+    See :option:`--dark` for a description of allowed values.
 
 .. option:: --format-dark COLOR
 
     Sets the color of the dark modules of the format information.
-    See :option:`--color` for a description of allowed values.
+    See :option:`--dark` for a description of allowed values.
 
 .. option:: --format-light COLOR
 
     Sets the color of the light modules of the format information.
-    See :option:`--color` for a description of allowed values.
+    See :option:`--dark` for a description of allowed values.
 
 .. option:: --version-dark COLOR
 
     Sets the color of the dark modules of the version information.
-    See :option:`--color` for a description of allowed values.
+    See :option:`--dark` for a description of allowed values.
 
 .. option:: --version-light COLOR
 
     Sets the color of the light modules of the version information.
-    See :option:`--color` for a description of allowed values.
+    See :option:`--dark` for a description of allowed values.
 
 .. option:: --dark-module COLOR
 
     Sets the color of the dark module.
-    See :option:`--color` for a description of allowed values.
+    See :option:`--dark` for a description of allowed values.
 
 
 
@@ -279,15 +279,15 @@ Saves the 2-Q QR code as SVG document with the given title.
 
 .. code-block:: bash
 
-    $ segno -o=number.svg --scale=10 --color="darkblue" "A Day in the Life"
+    $ segno -o=number.svg --scale=10 --dark darkblue "A Day in the Life"
 
 Saves the 1-L QR code as SVG document, using a scaling factor of 10 and the
 dark modules use the color "darkblue" instead of black.
 
 
 .. code-block:: bash
 
-    $ segno -o rain.png -s 10 --color="#003399" --micro RAIN
+    $ segno -o rain.png -s 10 --dark #003399 --micro RAIN
 
 
 Saves the Micro QR Code (M2-M) as PNG image, using the color #003399 for dark