Release 0.3.7

heuer · Jan 9, 2020 · a864c78 · a864c78
2 parents 708b793 + 2afb495
commit a864c78
Show file tree

Hide file tree

Showing 99 changed files with 639 additions and 290 deletions.
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -1,6 +1,15 @@
 Changes
 =======
 
+
+0.3.7 -- 2020-01-09
+-------------------
+* Documentation improvements: Added several examples, fixed docs
+* Fixed #62: PNG serializer adds only those colors to the PLTE which are
+  actually needed for the given (Micro) QR Code.
+* Minor performance improvements
+
+
 0.3.6 -- 2020-01-06
 -------------------
 * Backwards incompatibility change: QRCode.show() uses "dark" instead of
@@ -38,6 +47,9 @@ Changes
       qr.save('qrcode.png', scale=5, dark='darkred', data_dark='darkorange',
               data_light='yellow')
 
+  See `Colorful QR Codes <https://segno.readthedocs.io/en/stable/colorful-qrcodes.html>`_
+  for a description of available module names.
+
 
 0.3.5 -- 2020-01-03
 -------------------

diff --git a/MANIFEST.in b/MANIFEST.in
@@ -1 +1,2 @@
 include LICENSE *.txt *.rst
+exclude *.rtd
diff --git a/README.rst b/README.rst
@@ -10,12 +10,13 @@ QR Codes.
 
 Segno provides several serialization formats like Scalable Vector Graphics (SVG),
 Encapsulated PostScript (EPS), Portable Network Graphics (PNG),
-Portable Document Format (PDF), Portable Bitmap (PBM), Portable Arbitrary Map (PAM),
-LaTeX (PGF/TikZ), X PixMap (XBM), X Bitmap (XPM) or text output. None of these
-serializers require an external lib. Segno can provide more serialization
-formats via a plugin architecture.
+Portable Document Format (PDF), Portable Bitmap (PBM),
+LaTeX (PGF/TikZ), X PixMap (XBM), X Bitmap (XPM) etc. None of these
+serializers require an external lib.
 Further, it provides several high level functions to create QR Codes which encode
-contact data (MeCard, vCard) or WIFI configurations.
+`contact data (vCard, MeCard) <https://segno.readthedocs.io/en/stable/contact-information.html>`_,
+`EPC QR Codes <https://segno.readthedocs.io/en/stable/epc-qrcodes.html>`_,
+or `WIFI configurations <https://segno.readthedocs.io/en/stable/special-qrcode-factories.html#create-a-qr-code-for-a-wifi-configuration>`_.
 
 The project provides more than 1400 test cases (coverage >= 98%) to verify a
 standard conform QR Code and Micro QR Code generation acc. to ISO/IEC 18004:2015(E).
@@ -25,13 +26,18 @@ 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, ...)
+* A lot of `serialization formats <https://segno.readthedocs.io/en/stable/serializers.html#available-serializers>`_ (SVG, PNG, EPS, PDF, ...)
 * `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>`_
+* `Colorful QR Codes <https://segno.readthedocs.io/en/stable/colorful-qrcodes.html>`_
 
   .. image:: https://github.com/heuer/segno/raw/develop/docs/_static/yellow-submarine.png
-     :alt: Colorful 3-H QR Code encoding "Yellow Submarine"
+    :alt: Colorful 3-H QR Code encoding "Yellow Submarine"
+
+  ... works also with Micro QR Codes
+
+  .. image:: https://github.com/heuer/segno/raw/develop/docs/_static/colorful/rain.png
+    :alt: Colorful M4-Q Micro QR Code encoding "Rain"
 * `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/docrequirements.txt b/docrequirements.txt
diff --git a/docs/_static/.keep b/docs/_static/.keep
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/black-magic-woman.svg → docs/_static/cli/black-magic-woman.svg b/docs/_static/black-magic-woman.svg → docs/_static/cli/black-magic-woman.svg
diff --git a/docs/_static/boom-boom.svg → docs/_static/cli/boom-boom.svg b/docs/_static/boom-boom.svg → docs/_static/cli/boom-boom.svg
diff --git a/docs/_static/diamond.png → docs/_static/cli/diamond.png b/docs/_static/diamond.png → docs/_static/cli/diamond.png
diff --git a/docs/_static/dontgiveup.svg → docs/_static/cli/dontgiveup.svg b/docs/_static/dontgiveup.svg → docs/_static/cli/dontgiveup.svg
diff --git a/docs/_static/excited.png → docs/_static/cli/excited.png b/docs/_static/excited.png → docs/_static/cli/excited.png
diff --git a/docs/_static/hotel.png → docs/_static/cli/hotel.png b/docs/_static/hotel.png → docs/_static/cli/hotel.png
diff --git a/docs/_static/julia-02-01.png → docs/_static/cli/julia-02-01.png b/docs/_static/julia-02-01.png → docs/_static/cli/julia-02-01.png
diff --git a/docs/_static/julia-02-02.png → docs/_static/cli/julia-02-02.png b/docs/_static/julia-02-02.png → docs/_static/cli/julia-02-02.png
diff --git a/docs/_static/micro-qr-layla-version-m4.png → ..._static/cli/micro-qr-layla-version-m4.png b/docs/_static/micro-qr-layla-version-m4.png → ..._static/cli/micro-qr-layla-version-m4.png
diff --git a/..._static/micro-qr-little-wing-terminal.png → ...tic/cli/micro-qr-little-wing-terminal.png b/..._static/micro-qr-little-wing-terminal.png → ...tic/cli/micro-qr-little-wing-terminal.png
diff --git a/docs/_static/money-talks.png → docs/_static/cli/money-talks.png b/docs/_static/money-talks.png → docs/_static/cli/money-talks.png
diff --git a/docs/_static/private-investigations.svg → docs/_static/cli/private-investigations.svg b/docs/_static/private-investigations.svg → docs/_static/cli/private-investigations.svg
diff --git a/docs/_static/qr-layla-version-5.png → docs/_static/cli/qr-layla-version-5.png b/docs/_static/qr-layla-version-5.png → docs/_static/cli/qr-layla-version-5.png
diff --git a/docs/_static/qr-little-wing-terminal.png → docs/_static/cli/qr-little-wing-terminal.png b/docs/_static/qr-little-wing-terminal.png → docs/_static/cli/qr-little-wing-terminal.png
diff --git a/docs/_static/sa_yellow-submarine-02-01.png → ..._static/cli/sa_yellow-submarine-02-01.png b/docs/_static/sa_yellow-submarine-02-01.png → ..._static/cli/sa_yellow-submarine-02-01.png
diff --git a/docs/_static/sa_yellow-submarine-02-02.png → ..._static/cli/sa_yellow-submarine-02-02.png b/docs/_static/sa_yellow-submarine-02-02.png → ..._static/cli/sa_yellow-submarine-02-02.png
diff --git a/docs/_static/satellite.svg → docs/_static/cli/satellite.svg b/docs/_static/satellite.svg → docs/_static/cli/satellite.svg
diff --git a/docs/_static/thrill-gone.txt → docs/_static/cli/thrill-gone.txt b/docs/_static/thrill-gone.txt → docs/_static/cli/thrill-gone.txt
diff --git a/docs/_static/white-room.png → docs/_static/cli/white-room.png b/docs/_static/white-room.png → docs/_static/cli/white-room.png
diff --git a/docs/_static/colorful/alignment_dark.png b/docs/_static/colorful/alignment_dark.png
diff --git a/docs/_static/colorful/alignment_light.png b/docs/_static/colorful/alignment_light.png
diff --git a/docs/_static/colorful/dark.png b/docs/_static/colorful/dark.png
diff --git a/docs/_static/colorful/dark_module.png b/docs/_static/colorful/dark_module.png
diff --git a/docs/_static/colorful/data_dark.png b/docs/_static/colorful/data_dark.png
diff --git a/docs/_static/colorful/data_light.png b/docs/_static/colorful/data_light.png
diff --git a/docs/_static/colorful/finder_dark.png b/docs/_static/colorful/finder_dark.png
diff --git a/docs/_static/colorful/finder_light.png b/docs/_static/colorful/finder_light.png
diff --git a/docs/_static/colorful/format_dark.png b/docs/_static/colorful/format_dark.png
diff --git a/docs/_static/colorful/format_light.png b/docs/_static/colorful/format_light.png
diff --git a/docs/_static/colorful/light.png b/docs/_static/colorful/light.png
diff --git a/docs/_static/colorful/mqr_alignment_dark.png b/docs/_static/colorful/mqr_alignment_dark.png
diff --git a/docs/_static/colorful/mqr_alignment_light.png b/docs/_static/colorful/mqr_alignment_light.png
diff --git a/docs/_static/colorful/mqr_dark.png b/docs/_static/colorful/mqr_dark.png
diff --git a/docs/_static/colorful/mqr_dark_module.png b/docs/_static/colorful/mqr_dark_module.png
diff --git a/docs/_static/colorful/mqr_data_dark.png b/docs/_static/colorful/mqr_data_dark.png
diff --git a/docs/_static/colorful/mqr_data_light.png b/docs/_static/colorful/mqr_data_light.png
diff --git a/docs/_static/colorful/mqr_finder_dark.png b/docs/_static/colorful/mqr_finder_dark.png
diff --git a/docs/_static/colorful/mqr_finder_light.png b/docs/_static/colorful/mqr_finder_light.png
diff --git a/docs/_static/colorful/mqr_format_dark.png b/docs/_static/colorful/mqr_format_dark.png
diff --git a/docs/_static/colorful/mqr_format_light.png b/docs/_static/colorful/mqr_format_light.png
diff --git a/docs/_static/colorful/mqr_light.png b/docs/_static/colorful/mqr_light.png
diff --git a/docs/_static/colorful/mqr_quiet_zone.png b/docs/_static/colorful/mqr_quiet_zone.png
diff --git a/docs/_static/colorful/mqr_separator.png b/docs/_static/colorful/mqr_separator.png
diff --git a/docs/_static/colorful/mqr_timing_dark.png b/docs/_static/colorful/mqr_timing_dark.png
diff --git a/docs/_static/colorful/mqr_timing_light.png b/docs/_static/colorful/mqr_timing_light.png
diff --git a/docs/_static/colorful/mqr_version_dark.png b/docs/_static/colorful/mqr_version_dark.png
diff --git a/docs/_static/colorful/mqr_version_light.png b/docs/_static/colorful/mqr_version_light.png
diff --git a/docs/_static/colorful/quiet_zone.png b/docs/_static/colorful/quiet_zone.png
diff --git a/docs/_static/colorful/rain.png b/docs/_static/colorful/rain.png
diff --git a/docs/_static/colorful/separator.png b/docs/_static/colorful/separator.png
diff --git a/docs/_static/colorful/timing_dark.png b/docs/_static/colorful/timing_dark.png
diff --git a/docs/_static/colorful/timing_light.png b/docs/_static/colorful/timing_light.png
diff --git a/docs/_static/colorful/version_dark.png b/docs/_static/colorful/version_dark.png
diff --git a/docs/_static/colorful/version_light.png b/docs/_static/colorful/version_light.png
diff --git a/docs/_static/colorful/yellow-submarine.png b/docs/_static/colorful/yellow-submarine.png
diff --git a/docs/_static/spende-wikipedia.png → docs/_static/epc/spende-wikipedia.png b/docs/_static/spende-wikipedia.png → docs/_static/epc/spende-wikipedia.png
diff --git a/docs/_static/spende-wikipedia2.png → docs/_static/epc/spende-wikipedia2.png b/docs/_static/spende-wikipedia2.png → docs/_static/epc/spende-wikipedia2.png
diff --git a/docs/_static/geo/geo_data.png b/docs/_static/geo/geo_data.png
diff --git a/docs/_static/geo/geo_default.png b/docs/_static/geo/geo_default.png
diff --git a/docs/_static/structured_append_1_l-02-01.svg → ...static/sa/structured_append_1_l-02-01.svg b/docs/_static/structured_append_1_l-02-01.svg → ...static/sa/structured_append_1_l-02-01.svg
diff --git a/docs/_static/structured_append_1_l-02-02.svg → ...static/sa/structured_append_1_l-02-02.svg b/docs/_static/structured_append_1_l-02-02.svg → ...static/sa/structured_append_1_l-02-02.svg
diff --git a/docs/_static/structured_append_2_l.svg → docs/_static/sa/structured_append_2_l.svg b/docs/_static/structured_append_2_l.svg → docs/_static/sa/structured_append_2_l.svg
diff --git a/...structured_append_example_2_2-L-04-01.svg → ...structured_append_example_2_2-L-04-01.svg b/...structured_append_example_2_2-L-04-01.svg → ...structured_append_example_2_2-L-04-01.svg
diff --git a/...structured_append_example_2_2-L-04-02.svg → ...structured_append_example_2_2-L-04-02.svg b/...structured_append_example_2_2-L-04-02.svg → ...structured_append_example_2_2-L-04-02.svg
diff --git a/...structured_append_example_2_2-L-04-03.svg → ...structured_append_example_2_2-L-04-03.svg b/...structured_append_example_2_2-L-04-03.svg → ...structured_append_example_2_2-L-04-03.svg
diff --git a/...structured_append_example_2_2-L-04-04.svg → ...structured_append_example_2_2-L-04-04.svg b/...structured_append_example_2_2-L-04-04.svg → ...structured_append_example_2_2-L-04-04.svg
diff --git a/...tatic/structured_append_example_2_6-L.svg → ...ic/sa/structured_append_example_2_6-L.svg b/...tatic/structured_append_example_2_6-L.svg → ...ic/sa/structured_append_example_2_6-L.svg
diff --git a/docs/_static/wifi/wifi_data.png b/docs/_static/wifi/wifi_data.png
diff --git a/docs/_static/wifi/wifi_default.png b/docs/_static/wifi/wifi_default.png
diff --git a/docs/colorful-qrcodes.rst b/docs/colorful-qrcodes.rst
@@ -0,0 +1,272 @@
+Colorful QR Codes
+=================
+
+Almost all serializers support custom settings for the color of the dark and
+light modules of a (Micro) QR Code.
+
+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. :ref:`PNG <png>` and :ref:`SVG <svg>`),
+hexadecimal values like ``#RRGGBBAA`` are accepted.
+
+The value ``None`` is accepted by many serialization formats and indicates
+transparency, i.e. ``light=None`` to indicate that all light modules should
+be transparent.
+
+In almost all cases the color values are automatically converted into a
+meaningful value of the specific output format.
+
+The keywords are optional, if not provided, all serializers use a reasonable
+default value (dark modules are rendered in black, light modules in white).
+
+.. note:: Providing an alpha channel to a serializer which does not accept an
+    alpha channel results usually into an error.
+
+The PNG serializer supports more than two colors, every module type may have
+its own color.
+
+.. code-block:: python
+
+    >>> import segno
+    >>> # Force version 7 since smaller versions don't carry any version information (see below)
+    >>> qr = segno.make('Yellow Submarine', version=7, error='h')
+    >>> qr.save('yellow-submarine.png', scale=4, dark='darkred', data_dark='darkorange',
+                data_light='yellow')
+
+.. image:: _static/colorful/yellow-submarine.png
+    :alt: Colorful 7-H QR Code encoding "Yellow Submarine"
+
+
+.. code-block:: python
+
+    >>> import segno
+    >>> mqr = segno.make('Rain', error='q')
+    >>> mqr.save('rain.png', scale=4, dark='darkblue', data_dark='steelblue')
+
+.. image:: _static/colorful/rain.png
+    :alt: Colorful M4-Q QR Code encoding "RAIN"
+
+
+Module names
+------------
+
+The following examples show the results of all supported module types.
+The unaffected modules are rendered as grey or white modules, the red modules
+show the usage of the keyword.
+
+The keywords "dark" and "light" are supported by almost all serialization
+formats.
+
+
+dark
+~~~~
+
+Sets the (default) color of dark modules.
+
+.. image:: _static/colorful/dark.png
+    :alt: Picture showing the dark modules
+
+.. image:: _static/colorful/mqr_dark.png
+    :alt: Picture showing the dark modules of a Micro QR Code
+
+
+light
+~~~~~
+
+Sets the (default) color of light modules.
+
+.. image:: _static/colorful/light.png
+    :alt: Picture showing the light modules
+
+.. image:: _static/colorful/mqr_light.png
+    :alt: Picture showing the light modules of a Micro QR Code
+
+
+alignment_dark
+~~~~~~~~~~~~~~
+
+Sets the color of the dark alignment pattern modules.
+
+Micro QR Codes don't have alignment patterns.
+
+.. image:: _static/colorful/alignment_dark.png
+    :alt: Picture showing the dark alignment modules
+
+.. image:: _static/colorful/mqr_alignment_dark.png
+    :alt: Picture showing the dark alignment modules of a Micro QR Code (None)
+
+
+alignment_light
+~~~~~~~~~~~~~~~
+
+Sets the color of the light alignment pattern modules.
+
+Micro QR Codes don't have alignment patterns.
+
+.. image:: _static/colorful/alignment_light.png
+    :alt: Picture showing the light alignment modules
+
+.. image:: _static/colorful/mqr_alignment_light.png
+    :alt: Picture showing the light alignment modules of a Micro QR Code (None)
+
+
+dark_module
+~~~~~~~~~~~
+
+Sets the color of the dark module.
+
+Micro QR Codes don't have a dark module.
+
+.. image:: _static/colorful/dark_module.png
+    :alt: Picture showing the dark modules
+
+.. image:: _static/colorful/mqr_dark_module.png
+    :alt: Picture showing the dark modules of a Micro QR Code (None)
+
+
+data_dark
+~~~~~~~~~
+
+Sets the color of the dark data modules.
+
+.. image:: _static/colorful/data_dark.png
+    :alt: Picture showing the dark data modules
+
+.. image:: _static/colorful/mqr_data_dark.png
+    :alt: Picture showing the dark data modules of a Micro QR Code
+
+
+data_light
+~~~~~~~~~~
+
+Sets the color of the light data modules.
+
+.. image:: _static/colorful/data_light.png
+    :alt: Picture showing the light modules
+
+.. image:: _static/colorful/mqr_data_light.png
+    :alt: Picture showing the light modules of a Micro QR Code
+
+
+finder_dark
+~~~~~~~~~~~
+
+Sets the color of the dark modules of the finder pattern.
+
+.. image:: _static/colorful/finder_dark.png
+    :alt: Picture showing the dark finder modules
+
+.. image:: _static/colorful/mqr_finder_dark.png
+    :alt: Picture showing the dark finder modules of a Micro QR Code
+
+
+finder_light
+~~~~~~~~~~~~
+
+Sets the color of the light modules of the finder pattern.
+
+.. image:: _static/colorful/finder_light.png
+    :alt: Picture showing the light finder modules
+
+.. image:: _static/colorful/mqr_finder_light.png
+    :alt: Picture showing the light finder modules of a Micro QR Code
+
+
+format_dark
+~~~~~~~~~~~
+
+Sets the color of the dark modules of the format information.
+
+.. image:: _static/colorful/format_dark.png
+    :alt: Picture showing the dark format information modules
+
+.. image:: _static/colorful/mqr_format_dark.png
+    :alt: Picture showing the dark format information modules of a Micro QR Code (None)
+
+
+format_light
+~~~~~~~~~~~~
+
+Sets the color of the light modules of the format information.
+
+.. image:: _static/colorful/format_light.png
+    :alt: Picture showing the light format information modules
+
+.. image:: _static/colorful/mqr_format_light.png
+    :alt: Picture showing the light format information modules of a Micro QR Code (None)
+
+
+quiet_zone
+~~~~~~~~~~
+
+Sets the color of the quiet zone.
+
+.. image:: _static/colorful/quiet_zone.png
+    :alt: Picture showing the quiet zone
+
+.. image:: _static/colorful/mqr_quiet_zone.png
+    :alt: Picture showing the quiet zone of a Micro QR Code
+
+
+separator
+~~~~~~~~~
+
+Sets the color of the separator.
+
+.. image:: _static/colorful/separator.png
+    :alt: Picture showing the separator
+
+.. image:: _static/colorful/mqr_separator.png
+    :alt: Picture showing the separator of a Micro QR Code
+
+
+timing_dark
+~~~~~~~~~~~
+
+Sets the color of the dark modules of the timing pattern.
+
+.. image:: _static/colorful/timing_dark.png
+    :alt: Picture showing the dark timing pattern modules
+
+.. image:: _static/colorful/mqr_timing_dark.png
+    :alt: Picture showing the dark timing pattern modules of a Micro QR Code
+
+
+timing_light
+~~~~~~~~~~~~
+
+Sets the color of the light modules of the timing pattern.
+
+.. image:: _static/colorful/timing_light.png
+    :alt: Picture showing the light timing pattern modules
+
+.. image:: _static/colorful/mqr_timing_light.png
+    :alt: Picture showing the light timing pattern modules of a Micro QR Code
+
+
+version_dark
+~~~~~~~~~~~~
+
+Sets the color of the dark modules of the version information.
+
+Micro QR Codes and QR Codes lesser than version 7 don't carry any version information.
+
+.. image:: _static/colorful/version_dark.png
+    :alt: Picture showing the dark version modules
+
+.. image:: _static/colorful/mqr_version_dark.png
+    :alt: Picture showing the dark version modules of a Micro QR Code (None)
+
+
+version_light
+~~~~~~~~~~~~~
+
+Sets the color of the light modules of the version information.
+
+Micro QR Codes and QR Codes lesser than version 7 don't carry any version information.
+
+.. image:: _static/colorful/version_light.png
+    :alt: Picture showing the light version modules
+
+.. image:: _static/colorful/mqr_version_light.png
+    :alt: Picture showing the light version modules of a Micro QR Code (None)
diff --git a/docs/colors.rst b/docs/colors.rst