Finish 0.3.3

.gitignore

@@ -6,3 +6,6 @@
 htmlcov/*
 dist/*
 build/*
+venv/*
+sandbox/out/*.svg
+sandbox/out/*.png

CHANGES.rst

@@ -1,6 +1,24 @@
 Changes
 =======
 
+0.3.3 -- 2019-12-29
+-------------------
+* Fixed issue #54: PNGs with white color and transparent background were rendered
+  as transparent PNG with a *black* QR Code.
+* Removed test environments CPython 3.4 and 3.6 from tox
+* Improved documentation
+* Refactored source code
+* Added test cases
+* 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)
+* Moved module constants from ``segno.utils`` into ``segno.moduletypes``,
+  Constants from ``segno.utils`` will be removed within the next release.
+* 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).
+
 
 0.3.2 -- 2019-07-15
 -------------------

README.rst

@@ -17,8 +17,26 @@ formats via a plugin architecture.
 Further, it provides several high level functions to create QR Codes which encode
 contact data (MeCard, vCard) or WIFI configurations.
 
-The project provides more than 1000 test cases to verify a standard conform
-QR Code and Micro QR Code generation acc. to ISO/IEC 18004:2015(E).
+The project provides more than 1300 test cases (coverage >= 98%) to verify a
+standard conform QR Code and Micro QR Code generation acc. to ISO/IEC 18004:2015(E).
+
+
+Unique features
+---------------
+* Pure Python (supports 2.7, 3.7+, PyPy2 and PyPy3)
+* No dependencies
+* 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
+* `Structured Append mode <https://segno.readthedocs.io/en/stable/structured-append.html>`_
+* `Simple, user-friendly API <https://segno.readthedocs.io/en/stable/api.html>`_
+  ::
+
+    import segno
+    qr = segno.make('Yellow Submarine')
+    qr.save('yellow-submarine.png')
+
+
 
 Installation
 ------------

docs/api-low-level.rst

@@ -2,16 +2,16 @@ Segno's low level API
 =====================
 
 :py:func:`segno.make`, :py:func:`segno.make_qr`, and :py:func:`segno.make_micro`
-return a :py:class:`segno.QRCode` which implements almost no logic but uses the
-result of :py:func:`segno.encoder.encode` glued together with the functionality
-of :py:mod:`segno.writers` to provide a simple (supposed to be user-friendly)
-API.
+return a :py:class:`segno.QRCode` instance which implements almost no logic but
+uses the result of :py:func:`segno.encoder.encode` glued together with the
+functionality of :py:mod:`segno.writers` to provide a simple, user-friendly API.
 
 A completely different API is possible by utilizing
 :py:func:`segno.encoder.encode` which returns just a tuple:
-``(matrix, version, error, mask, segments)``. The module
-:py:mod:`segno.writers` is independent of the :py:mod:`segno.encoder`
-module and vice versa.
+``(matrix, version, error, mask, segments)``.
+
+The module :py:mod:`segno.writers` (expecting just a matrix) is independent of
+the :py:mod:`segno.encoder` module and vice versa.
 
 
 segno.encoder

docs/api.rst

@@ -16,6 +16,13 @@ Utilities
     :members:
 
 
+Module Types
+------------
+
+.. automodule:: segno.moduletypes
+    :members:
+
+
 High level QR Code factories
 ----------------------------
 

docs/error-correction-boost.rst → docs/boost-error-correction-level.rst

@@ -1,5 +1,5 @@
-Error Correction Level Boosting
-===============================
+Boost Error Correction Level
+============================
 
 If the user does not provide any :option:`--version <segno --version>` or
 :paramref:`version <segno.make.version>` keyword parameter for :func:`segno.make`,
@@ -16,9 +16,9 @@ To prevent any error correction level enhancement, Segno provides the
 :option:`--no-error-boost <segno --no-error-boost>` option and
 :paramref:`boost_error=False <segno.make.boost_error>` option for :func:`segno.make`.
 
-It's recommended to keep the default error level correction boosting, because
-a better error correction improves the possibility that the QR Code can be read
-by average QR Code decoders under all circumstances.
+It's recommended to keep the error level correction boosting, because
+a better error correction level improves the probability that the QR Code can be
+read by average QR Code decoders under all circumstances.
 
 
 Examples

docs/colors.rst

@@ -4,10 +4,10 @@ Colors
 Almost all serializers support custom settings for the color of the dark modules
 and the background (light modules) of a (Micro) QR Code.
 
-The color values can be provides as tuple (``(R, G, B)``), as web color name
+The color values can be provided as tuple (``(R, G, B)``), as web color name
 (like 'red') or as hexadecimal ``#RRGGBB`` value (i.e. '#085A75'). If alpha
-transparency is supported (i.e. PNG and SVG), hexadecimal values like
-``#RRGGBBAA`` are accepted.
+transparency is supported (i.e. :ref:`PNG <png>` and :ref:`SVG <svg>`),
+hexadecimal values like ``#RRGGBBAA`` are accepted.
 
 In almost all cases the color values are automatically converted into a
 meaningful value of the specific output format.

docs/command-line.rst

@@ -64,7 +64,7 @@ Error correction level
 
 The default error correction level is "L" (or any better if
 :option:`--no-error-boost <segno --no-error-boost>` was not set, c.f.
-:doc:`error-correction-boost`), use the
+:doc:`boost-error-correction-level`), use the
 :option:`--error <segno --error>` parameter to change it::
 
     $ segno --error=q "Ain't no grave"

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.0                  1.3.4                  1.3.0                     |version|
+    Library version                                                     6.1                      1.2.1                  1.3.4                  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
@@ -70,7 +70,7 @@ Performance
 -----------
 
 Some performance indicators. The script `benchmarks.py`_ ran on a
-Mac Mini 2,26 Core2 Duo using CPython 2.7.15. Each SVG / PNG image uses a
+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

@@ -2,8 +2,10 @@ Segno - Python QR Code and Micro QR Code encoder
 ================================================
 
 Segno generates QR Codes and Micro QR Codes according to ``ISO/IEC 18004:2015(E)``.
-Aside from other Python QR Code generators, Segno has no 3rd party dependencies,
-provides :doc:`a lot of output formats <serializers>` and is very simple to use.
+
+Aside from other Python QR Code generators, Segno provides
+:doc:`a lot of output formats <serializers>` without 3rd party dependencies and
+is very simple to use.
 
 Contents:
 
@@ -13,7 +15,7 @@ Contents:
     command-line
     make
     structured-append
-    error-correction-boost
+    boost-error-correction-level
     serializers
     colors
     special-qrcode-factories
@@ -23,6 +25,7 @@ Contents:
     plugins
     api
     api-low-level
+    python2
 
 
 Indices and tables

docs/man/segno.rst

@@ -12,7 +12,7 @@ Description
 
 :program:`segno` creates QR Codes and Micro QR Codes.
 
-It can be used to print the codes to a terminal or to serialize the them
+It can be used to print the codes to a terminal or to serialize them
 in several output formats (like SVG and PNG).
 
 

docs/python2.rst

@@ -0,0 +1,8 @@
+Python 2 Statement
+==================
+
+While Segno becomes a Python 3-first package, Python 2.7 is still supported
+after January 2020.
+
+There are no plans to drop support for Python 2, Segno supports it
+as long as technically possible.

docs/replace-qrcode-libs.rst

@@ -6,5 +6,5 @@ common Python QR Code libs like `PyQRCode`_ and `qrcode`_ with Segno.
 
 
 .. _Segno Mimos: https://github.com/heuer/segno-mimos
-.. _qrcode: https://pypi.python.org/pypi/qrcode/
-.. _PyQRCode: https://pypi.python.org/pypi/PyQRCode/
+.. _qrcode: https://pypi.org/project/qrcode/
+.. _PyQRCode: https://pypi.org/project/PyQRCode/

docs/serializers.rst

@@ -95,43 +95,47 @@ accepted by the specific serializer.
 Available serializers
 ---------------------
 
-SVG
-    Scalable Vector Graphics (SVG). The serializer provides all default features
-    (scale, border, color and background color) and many more to customize the
-    output, see :ref:`SVG <svg>` for details. SVGZ (compressed SVG) is supported
-    as well.
-
-PNG
-    Portable Network Graphics (PNG). The serializer provides all default features
-    (scale, border, color and background color) and a few more to customize the
-    output, see :ref:`PNG <png>` for details.
+ANSI
+    ANSI escape code. The serializer supports the border keyword, only.
+    See :ref:`ANSI <ansi>` for details.
 
 EPS
     Encapsulated PostScript (EPS). The serializer provides all default features
     (scale, border, color and background color), see :ref:`EPS <eps>` for details.
 
-PDF
-    Portable Document Format (PDF). The serializer provides all default features
-    (scale, border, color and background color), see :ref:`PDF <pdf>` for details.
+LaTeX
+    LaTeX / PGF/TikZ. The serializer provides no background color, but all
+    other default features (scale, border, color) are supported, see
+    :ref:`LaTeX <latex>` for details.
 
-TXT
-    Text output. The serializer does not support any scale or color, but the
-    character for the dark and white modules may be specified via `color`
-    and `background`, see :ref:`TXT <txt>` for details.
+PAM
+    Portable Arbitrary Map (PAM). The serializer provides all default features
+    (scale, border, color and background color), see :ref:`PAM <pam>` for details.
 
 PBM
     Portable Bitmap (PBM). The serializer does not support any coloring,
     but the common featurs like scale and border are supported, see :ref:`PBM <pbm>`
     for details.
 
-PAM
-    Portable Arbitrary Map (PAM). The serializer provides all default features
-    (scale, border, color and background color), see :ref:`PAM <pam>` for details.
+PDF
+    Portable Document Format (PDF). The serializer provides all default features
+    (scale, border, color and background color), see :ref:`PDF <pdf>` for details.
 
-LaTeX
-    LaTeX / PGF/TikZ. The serializer provides no background color, but all
-    other default features (scale, border, color) are supported, see
-    :ref:`LaTeX <latex>` for details.
+PNG
+    Portable Network Graphics (PNG). The serializer provides all default features
+    (scale, border, color and background color) and a few more to customize the
+    output, see :ref:`PNG <png>` for details.
+
+SVG
+    Scalable Vector Graphics (SVG). The serializer provides all default features
+    (scale, border, color and background color) and many more to customize the
+    output, see :ref:`SVG <svg>` for details. SVGZ (compressed SVG) is supported
+    as well.
+
+TXT
+    Text output. The serializer does not support any scale or color, but the
+    character for the dark and white modules may be specified via `color`
+    and `background`, see :ref:`TXT <txt>` for details.
 
 XBM
     X BitMap (XBM). The serializer does not support any coloring, but scale

man/segno.1

@@ -1,6 +1,6 @@
 .\" Man page generated from reStructuredText.
 .
-.TH "SEGNO" "1" "Jul 15, 2019" "" "Segno"
+.TH "SEGNO" "1" "Dec 29, 2019" "" "Segno"
 .SH NAME
 segno \- Segno QR Code encoder
 .
@@ -37,7 +37,7 @@ level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
 .sp
 \fBsegno\fP creates QR Codes and Micro QR Codes.
 .sp
-It can be used to print the codes to a terminal or to serialize the them
+It can be used to print the codes to a terminal or to serialize them
 in several output formats (like SVG and PNG).
 .SH COMMAND LINE OPTIONS
 .INDENT 0.0

sandbox/make_charts.py

@@ -2,8 +2,7 @@
 """\
 Create the benchmark charts.
 """
-import glob
-import shutil
+import os
 import csv
 from decimal import Decimal
 import pygal
@@ -46,17 +45,16 @@ def create_charts():
                 png_data.append((name.replace(' PNG 1-M', ''), val))
             elif ' SVG' in name:
                 svg_data.append((name.replace(' SVG', ''), val))
-    for data, title, filename in ((create_1m_data, 'Create a 1-M QR Code', 'out/chart_create_1m.svg'),
-                                  (create_7q_data, 'Create a 7-Q QR Code', 'out/chart_create_7q.svg'),
-                                  (create_30h_data, 'Create a 30-H QR Code', 'out/chart_create_30h.svg'),
-                                  (svg_data, 'Create a 1-M QR Code and write SVG', 'out/chart_svg.svg'),
-                                  (png_data, 'Create a 1-M QR Code and write PNG', 'out/chart_png.svg')):
+    output_dir = os.path.abspath('../docs/_static/')
+    for data, title, filename in ((create_1m_data, 'Create a 1-M QR Code', os.path.join(output_dir, 'chart_create_1m.svg')),
+                                  (create_7q_data, 'Create a 7-Q QR Code', os.path.join(output_dir, 'chart_create_7q.svg')),
+                                  (create_30h_data, 'Create a 30-H QR Code', os.path.join(output_dir, 'chart_create_30h.svg')),
+                                  (svg_data, 'Create a 1-M QR Code and write SVG', os.path.join(output_dir, 'chart_svg.svg')),
+                                  (png_data, 'Create a 1-M QR Code and write PNG', os.path.join(output_dir, 'chart_png.svg'))):
         create_chart(title,
                      [(name, [{'value': float(val), 'color': color_map[name], 'label': name}]) for name, val in sorted(data, key=lambda t: Decimal(t[1]))],
                      filename)
 
 
 if __name__ == '__main__':
     create_charts()
-    for chart in glob.glob('out/chart*.svg'):
-        shutil.copy(chart, '../docs/_static/')

sandbox/out/results.csv

@@ -1,23 +1,23 @@
-PyQRCode create 1-M,28.68
-PyQRCodeNG create 1-M,20.68
-qrcodegen create 1-M,15.42
-qrcode create 1-M,11.53
-Segno create 1-M,7.19
-PyQRCode create 7-Q,135.53
-PyQRCodeNG create 7-Q,105.96
-qrcode create 7-Q,50.89
-Segno create 7-Q,32.45
-PyQRCode create 30-H,1284.49
-PyQRCodeNG create 30-H,1055.03
-qrcode create 30-H,480.62
-Segno create 30-H,332.07
-PyQRCode SVG,29.97
-PyQRCodeNG SVG,29.78
-qrcodegen SVG,16.31
-qrcode SVG path,57.06
-qrcode SVG rects,53.43
-Segno SVG,8.69
-PyQRCode PNG 1-M,76.97
-PyQRCodeNG PNG 1-M,71.61
-qrcode PNG 1-M,17.11
-Segno PNG 1-M,12.37
+PyQRCode create 1-M,8.17
+PyQRCodeNG create 1-M,6.13
+qrcodegen create 1-M,5.17
+qrcode create 1-M,3.71
+Segno create 1-M,2.02
+PyQRCode create 7-Q,36.94
+PyQRCodeNG create 7-Q,29.07
+qrcode create 7-Q,16.73
+Segno create 7-Q,10.06
+PyQRCode create 30-H,354.08
+PyQRCodeNG create 30-H,278.91
+qrcode create 30-H,163.18
+Segno create 30-H,103.77
+PyQRCode SVG,8.46
+PyQRCodeNG SVG,8.47
+qrcodegen SVG,5.63
+qrcode SVG path,4.69
+qrcode SVG rects,5.73
+Segno SVG,2.29
+PyQRCode PNG 1-M,15.70
+PyQRCodeNG PNG 1-M,14.09
+qrcode PNG 1-M,4.66
+Segno PNG 1-M,3.51