Release 0.3.4

heuer · Jan 2, 2020 · 77daa1e · 77daa1e
2 parents d7558d2 + 883330e
commit 77daa1e
Show file tree

Hide file tree

Showing 75 changed files with 1,081 additions and 312 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,6 +1,24 @@
 Changes
 =======
 
+0.3.4 -- 2020-01-02
+-------------------
+* Fixed issue #54: After last change (see 0.3.3), white background with transparent
+  QR Code did not work. Enhanced test suite to cover all possible inputs
+  for PNG grayscale mode
+* Removed interpretation of ``addad`` from PNG serializer.
+  Contradicts the claim to create small images by default.
+  It still belongs to the function signature but will be removed in release 0.4.0
+* The option ``--no-ad`` (CLI) is still available but ignored and will be removed
+  in release 0.4.0. Removed the option from man page.
+* Added option to PNG serializer to provide more than two colors. Each module
+  type may have its own color.
+* Added support for EPC QR Codes.
+* Fixed bug in ``helpers.make_vcard_data`` function (the "source" URL was not
+  used, but the usual URL was added to the SOURCE field)
+* Better test coverage for the ``segno.helpers`` module
+
+
 0.3.3 -- 2019-12-29
 -------------------
 * Fixed issue #54: PNGs with white color and transparent background were rendered

diff --git a/LICENSE b/LICENSE
@@ -1,4 +1,4 @@
-Copyright (c) 2016 - 2019, Lars Heuer
+Copyright (c) 2016 - 2020, Lars Heuer
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,

diff --git a/README.rst b/README.rst
@@ -28,6 +28,10 @@ Unique features
 * A lot of serialization formats (SVG, PNG, EPS, PDF, PAM, XPM, ...)
 * `Fastest (pure Python) QR Code encoder <https://segno.readthedocs.io/en/stable/comparison-qrcode-libs.html#performance>`_
 * Micro QR Codes
+* `Colorful QR Codes <https://segno.readthedocs.io/en/stable/serializers.html#more-colorful-qr-codes>`_
+
+  .. image:: https://github.com/heuer/segno/raw/develop/docs/_static/yellow-submarine.png
+     :alt: Colorful 3-H QR Code encoding "Yellow Submarine"
 * `Structured Append mode <https://segno.readthedocs.io/en/stable/structured-append.html>`_
 * `Simple, user-friendly API <https://segno.readthedocs.io/en/stable/api.html>`_
   ::

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/yellow-submarine.png b/docs/_static/yellow-submarine.png
diff --git a/docs/changes.rst b/docs/changes.rst
@@ -0,0 +1 @@
+.. include:: ../CHANGES.rst
diff --git a/docs/comparison-qrcode-libs.rst b/docs/comparison-qrcode-libs.rst
@@ -15,7 +15,7 @@ Features
     Description                                                         `qrcode`_                `PyQRCode`_            `PyQRCodeNG`_          `qrcodegen`_              `Segno`_
     ================================================================    =====================    ===================    ===================    ======================    ========
     Library license                                                     `BSD`_                   `BSD`_                 `BSD`_                 `MIT`_                    `BSD`_
-    Library version                                                     6.1                      1.2.1                  1.3.4                  1.5.0                     |version|
+    Library version                                                     6.1                      1.2.1                  1.3.6                  1.5.0                     |version|
     Mode Numeric                                                        Yes                      Yes                    Yes                    Yes                       Yes
     Mode Alphanumeric                                                   Yes                      Yes                    Yes                    Yes                       Yes
     Mode Byte                                                           Yes                      Yes                    Yes                    Yes                       Yes
@@ -102,7 +102,7 @@ Create a 30-H QR Code
 
 
 Create a QR Code and serialize it as SVG
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Create a QR Code 1-M "QR Code Symbol" and serialize it as SVG document.
 
@@ -112,7 +112,7 @@ Create a QR Code 1-M "QR Code Symbol" and serialize it as SVG document.
 
 
 Create a QR Code and serialize it as PNG
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Create a QR Code 1-M "QR Code Symbol" and serialize it as PNG image.
 

diff --git a/docs/contact-information.rst b/docs/contact-information.rst
@@ -0,0 +1,61 @@
+Creating a QR Code encoding contact information
+===============================================
+
+MeCard
+------
+
+The function :py:func:`segno.helpers.make_mecard` returns a QR Code which encodes
+contact information as MeCard.
+
+.. code-block:: python
+
+    >>> from segno import helpers
+    >>> qr = helpers.make_mecard(name='Doe,John', email='me@example.org', phone='+1234567')
+    >>> qr.designator
+    '3-L'
+    >>> # Some params accept multiple values, like email, phone, url
+    >>> qr = helpers.make_mecard(name='Doe,John', email=('me@example.org', 'another@example.org'), url=['http://www.example.org', 'https://example.org/~joe'])
+    >>> qr.save('my-mecard.svg')
+
+A factory function which returns the MeCard as string is available as well.
+
+.. code-block:: python
+
+    >>> import segno
+    >>> from segno import helpers
+    >>> mecard = helpers.make_mecard_data(name='Doe,John', email='me@example.org', phone='+1234567')
+    >>> mecard
+    'MECARD:N:Doe,John;TEL:+1234567;EMAIL:me@example.org;;'
+    >>> qr = segno.make(mecard, error='H')
+    >>> qr.designator
+    '6-H'
+
+
+vCard
+-----
+
+The function :py:func:`segno.helpers.make_vcard` returns a QR Code which encodes
+contact information as vCard version 3.0.
+
+.. code-block:: python
+
+    >>> from segno import helpers
+    >>> qr = helpers.make_vcard(name='Doe;John', displayname='John Doe', email='me@example.org', phone='+1234567')
+    >>> qr.designator
+    '5-L'
+    >>> # Some params accept multiple values, like email, phone, url
+    >>> qr = helpers.make_vcard(name='Doe;John', displayname='John Doe', email=('me@example.org', 'another@example.org'), url=['http://www.example.org', 'https://example.org/~joe'])
+    >>> qr.save('my-vcard.svg')
+
+A factory function which returns the vCard as string is available as well.
+
+.. code-block:: python
+
+    >>> import segno
+    >>> from segno import helpers
+    >>> vcard = helpers.make_vcard_data(name='Doe;John', displayname='John Doe', email='me@example.org', phone='+1234567')
+    >>> vcard
+    'BEGIN:VCARD\r\nVERSION:3.0\r\nN:Doe;John\r\nFN:John Doe\r\nEMAIL:me@example.org\r\nTEL:+1234567\r\nEND:VCARD\r\n'
+    >>> qr = segno.make(vcard, error='H')
+    >>> qr.designator
+    '9-H'
diff --git a/docs/epc-qrcodes.rst b/docs/epc-qrcodes.rst
@@ -0,0 +1,66 @@
+EPC QR Codes
+============
+
+European Payments Council Quick Response Code (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.
+
+See the `EPC guidelines (PDF document) <https://www.europeanpaymentscouncil.eu/sites/default/files/KB/files/EPC069-12%20v2.1%20Quick%20Response%20Code%20-%20Guidelines%20to%20Enable%20the%20Data%20Capture%20for%20the%20Initiation%20of%20a%20SCT.pdf>`_
+for more information.
+
+The function :py:func:`segno.helpers.make_epc_qr` is used to create a EPC QR Code.
+It is not possible to modify the error correction level or to change the version
+of the QR Code. The EPC guidelines specify that the error correction level is
+fixed to "M" and the QR Code version must not be higher than 13.
+
+.. code-block:: python
+
+    >>> from segno import helpers
+    >>> qr = helpers.make_epc_qr(name='Wikimedia Foerdergesellschaft', iban='DE33100205000001194700', amount=20, text='Spende fuer Wikipedia')
+    >>> qr.save('spende-wikipedia.png', scale=3)
+
+.. image:: _static/spende-wikipedia.png
+    :alt: EPC QR Code
+
+The QR Code shown above encodes the following information::
+
+    BCD
+    002
+    2
+    SCT
+
+    Wikimedia Foerdergesellschaft
+    DE33100205000001194700
+    EUR20
+
+By default, the function uses the minimal possible encoding to encode the
+provided data. If another encoding, i.e. UTF-8, is required, the user may specify
+the encoding with an integer referring to one of the supported encodings
+(1: UTF-8, 2: ISO 8859-1, 3: ISO 8859-2, 4: ISO 8859-4, 5: ISO 8859-5,
+6: ISO 8859-7, 7: ISO 8859-10, 8: ISO 8859-15)
+
+
+.. code-block:: python
+
+    >>> from segno import helpers
+    >>> qr = helpers.make_epc_qr(name='Wikimedia Foerdergesellschaft', iban='DE33100205000001194700', amount=13.05, text='Spende fuer Wikipedia', encoding=1)
+    >>> qr.save('spende-wikipedia2.png', scale=3)
+
+.. image:: _static/spende-wikipedia2.png
+    :alt: EPC QR Code
+
+Decoded infomation::
+
+    BCD
+    002
+    1
+    SCT
+
+    Wikimedia Foerdergesellschaft
+    DE33100205000001194700
+    EUR13.05
+
+
+    Spende fuer Wikipedia
+
diff --git a/docs/index.rst b/docs/index.rst
@@ -19,13 +19,16 @@ Contents:
     serializers
     colors
     special-qrcode-factories
+    contact-information
+    epc-qrcodes
     comparison-qrcode-libs
     man/index
     replace-qrcode-libs
     plugins
     api
     api-low-level
     python2
+    changes
 
 
 Indices and tables

diff --git a/docs/man/segno.rst b/docs/man/segno.rst
@@ -171,10 +171,6 @@ Command Line Options
 
     Sets the DPI value of the PNG file
 
-.. option:: --no-ad
-
-    Omits the "Software" comment in the PNG file
-
 
 Exit Status
 -----------

diff --git a/docs/replace-qrcode-libs.rst b/docs/replace-qrcode-libs.rst
@@ -2,9 +2,10 @@ Replace existing QR Code libs with Segno
 ========================================
 
 The sub-project `Segno Mimos`_ provides APIs which are usable to replace
-common Python QR Code libs like `PyQRCode`_ and `qrcode`_ with Segno.
+common Python QR Code libs like `PyQRCode`_ and `qrcode`_ with Segno while
+keeping the API of the replaced libs.
 
 
-.. _Segno Mimos: https://github.com/heuer/segno-mimos
+.. _Segno Mimos: https://pypi.org/project/segno-mimos/
 .. _qrcode: https://pypi.org/project/qrcode/
 .. _PyQRCode: https://pypi.org/project/PyQRCode/
diff --git a/docs/serializers.rst b/docs/serializers.rst
@@ -31,8 +31,8 @@ a custom border, the user may specify the border explicitly.
 
 Most serializers accept a ``scale`` parameter which indicates the scaling
 factor of the serialization. By default, the scaling factor is ``1`` which means
-that the dark / light modules of a (Micro) QR Code is interpreted as one unit in
-the specific user space (i.e. 1 pixel for the :ref:`PNG <png>` serializer or
+that size of a dark / light module is interpreted as one unit in the specific
+user space (i.e. 1 pixel for the :ref:`PNG <png>` serializer or
 1 point (1/72 of an inch) in :ref:`EPS <eps>`). Some serializers
 (like :ref:`PNG <png>`) accept only an integer value or convert the provided
 scaling factor to an integer. Other, like :ref:`SVG <svg>` and :ref:`EPS <eps>`,
@@ -92,6 +92,24 @@ See :py:meth:`segno.QRCode.save` for a complete reference which parameters are
 accepted by the specific serializer.
 
 
+More colorful QR Codes
+----------------------
+
+The PNG serializer supports an optional color mapping which can define a specific
+color for each module type.
+
+.. code-block:: python
+
+    >>> import segno
+    >>> from segno import moduletypes as mt
+    >>> qr = segno.make('Yellow Submarine', error='h')
+    >>> 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('yellow-submarine.png', scale=5, colormap=colormap)
+
+.. image:: _static/yellow-submarine.png
+    :alt: Colorful 3-H QR Code encoding "Yellow Submarine"
+
+
 Available serializers
 ---------------------
 

diff --git a/docs/special-qrcode-factories.rst b/docs/special-qrcode-factories.rst
@@ -2,7 +2,8 @@ Special QR Code factory functions
 =================================
 
 The :py:mod:`segno.helpers` module provides factory functions to create common QR Codes
-for encoding WIFI configurations, MeCards or geographic locations.
+for encoding WIFI configurations, :doc:`vCards and MeCards <contact-information>`,
+:doc:`EPC QR Codes <epc-qrcodes>` or geographic locations.
 
 The created QR Codes use at minimum the error correction level "L". If a better
 error correction level is possible without changing the QR Code version, the
@@ -66,64 +67,3 @@ available.
     '4-H'
 
 
-Creating a QR Code encoding contact information
------------------------------------------------
-
-MeCard
-^^^^^^
-
-The function :py:func:`segno.helpers.make_mecard` returns a QR Code which encodes
-contact information as MeCard.
-
-.. code-block:: python
-
-    >>> from segno import helpers
-    >>> qr = helpers.make_mecard(name='Doe,John', email='me@example.org', phone='+1234567')
-    >>> qr.designator
-    '3-L'
-    >>> # Some params accept multiple values, like email, phone, url
-    >>> qr = helpers.make_mecard(name='Doe,John', email=('me@example.org', 'another@example.org'), url=['http://www.example.org', 'https://example.org/~joe'])
-    >>> qr.save('my-mecard.svg')
-
-A factory function which returns the MeCard as string is available as well.
-
-.. code-block:: python
-
-    >>> import segno
-    >>> from segno import helpers
-    >>> mecard = helpers.make_mecard_data(name='Doe,John', email='me@example.org', phone='+1234567')
-    >>> mecard
-    'MECARD:N:Doe,John;TEL:+1234567;EMAIL:me@example.org;;'
-    >>> qr = segno.make(mecard, error='H')
-    >>> qr.designator
-    '6-H'
-
-
-vCard
-^^^^^
-
-The function :py:func:`segno.helpers.make_vcard` returns a QR Code which encodes
-contact information as vCard version 3.0.
-
-.. code-block:: python
-
-    >>> from segno import helpers
-    >>> qr = helpers.make_vcard(name='Doe;John', displayname='John Doe', email='me@example.org', phone='+1234567')
-    >>> qr.designator
-    '5-L'
-    >>> # Some params accept multiple values, like email, phone, url
-    >>> qr = helpers.make_vcard(name='Doe;John', displayname='John Doe', email=('me@example.org', 'another@example.org'), url=['http://www.example.org', 'https://example.org/~joe'])
-    >>> qr.save('my-vcard.svg')
-
-A factory function which returns the vCard as string is available as well.
-
-.. code-block:: python
-
-    >>> import segno
-    >>> from segno import helpers
-    >>> vcard = helpers.make_vcard_data(name='Doe;John', displayname='John Doe', email='me@example.org', phone='+1234567')
-    >>> vcard
-    'BEGIN:VCARD\r\nVERSION:3.0\r\nN:Doe;John\r\nFN:John Doe\r\nEMAIL:me@example.org\r\nTEL:+1234567\r\nEND:VCARD\r\n'
-    >>> qr = segno.make(vcard, error='H')
-    >>> qr.designator
-    '9-H'
diff --git a/man/segno.1 b/man/segno.1
@@ -207,11 +207,6 @@ PNG Options.INDENT 0.0
 .B \-\-dpi DPI
 Sets the DPI value of the PNG file
 .UNINDENT
-.INDENT 0.0
-.TP
-.B \-\-no\-ad
-Omits the “Software” comment in the PNG file
-.UNINDENT
 .SH EXIT STATUS
 .sp
 \fBsegno\fP exits 0 on success, and >0 if an error occurs.

diff --git a/sandbox/benchmarks.py b/sandbox/benchmarks.py
@@ -103,7 +103,7 @@ def create30h_pyqrcodeng(data='QR Code Symbol'):
 
     def svg_pyqrcodeng(data='QR Code Symbol'):
         """PyQRCodeNG SVG"""
-        pyqrcode.create(data, error='m').svg('out/pyqrcodeng_%s.svg' % data, scale=10)
+        pyqrcodeng.create(data, error='m').svg('out/pyqrcodeng_%s.svg' % data, scale=10)
 
     def png_pyqrcodeng(data='QR Code Symbol'):
         """PyQRCodeNG PNG 1-M"""