Merge branch 'release/0.2.4'

CHANGES.rst

@@ -1,9 +1,39 @@
 Changes
 =======
 
+0.2.4 -- 2017-01-31
+-------------------
+* Fixed #33: Some Micro QR Codes may be unreadable due to wrong
+  format information. Further, M1 and M3 codes may be wrong due to wrong
+  encoding of final data symbol character (8 bits instead of (correct) 4 bits).
+  Thanks to Nicolas Boullis for the bug report, initial fix, tests and patience.
+* Fixed #34: Change default error level from "M" to "L" to avoid surprises that
+  the content does not fit into the provided version. This change is somewhat
+  backwards incompatible.
+* Fixed #35: Check of user supplied mask pattern index was wrong.
+* Fixed #36: Wrong placement of codeword in M1 and M3 symbols.
+* Fixed #37: Generation of M1 / M3 symbols fail if the data modules are
+  completely filled.
+* Fixed #38: Optimized mask pattern choosing algorithm: If the user supplied
+  a preferred mask, the mask evaluation step is skipped and the preferred mask
+  is chosen
+* Added more internal checks to ensure correct (Micro) QR Codes; provided
+  helpful exceptions
+* Removed ``writers.get_writable`` (replaced by ``writers.writable``)
+* Added support for serializing QR Codes as XBM (X BitMap) (supports
+  black / white images)
+* Added support for serializing QR Codes as XPM (X PixMap) (supports colors and
+  transparency)
+* Added support for encoding contact information as vCard version 3.0
+  (``segno.helpers``)
+* Added -V shortcut to Segno's command line script to show version information
+* Better test coverage for command line script
+* Better test coverage for M1 and M3 symbols
+
+
 0.2.3 -- 2016-10-17
 -------------------
-* Fixed #27: E-mail URI is wrong if CC or BCC is used.
+* Fixed #27: Email URI is wrong if CC or BCC is used.
 * Fixed #32: Don't add version attribute if SVG >= 2.0
 * Deprecated ``writers.get_writable``; use ``writers.writable``
   ``writers.writable`` closes file-like objects automatically (if necessary);
@@ -19,11 +49,10 @@ Changes
 -------------------
 * Command line script reports Segno's version (``--ver``) and the version
   is also mentioned in the help message (``-h``) (#24)
-* Support for creating E-mail addresses or complete messages (``segno.helpers``)
+* Support for creating email addresses or complete messages (``segno.helpers``)
 * Internal optimizations and more correct minimal version finding (#26)
 
 
-
 0.2.1 -- 2016-09-15
 -------------------
 * Fixed Python packaging (source distribution did not work), again

LICENSE.txt

@@ -1,4 +1,4 @@
-Copyright (c) 2016, Lars Heuer
+Copyright (c) 2016 - 2017, Lars Heuer
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without modification,

README.rst

@@ -3,16 +3,18 @@ Segno -- Python QR Code and Micro QR Code encoder
 
 Segno is a QR Code and Micro QR Code encoder which has no further dependencies.
 
-This package implements main parts of ISO/IEC 18004:2006(E) / ISO/IEC 18004:2015(E)
-and produces Micro QR Codes and QR Codes with nearly no effort.
-
-Segno provides several serialization formats like SVG, EPS, PNG, PDF, PBM,
-LaTeX (PGF/TikZ) or text output. None of these serializers require an external
-lib. Segno could provide more serialization formats via a plugin architecture.
+This package implements ISO/IEC 18004:2006(E) / ISO/IEC 18004:2015(E) "QR Code bar
+code symbology specification" and produces Micro QR Codes and QR Codes with
+nearly no effort.
+
+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 could provide more serialization
+formats via a plugin architecture.
 Further, it provides several high level function to create QR Codes which encode
-contact data (MeCard) or WIFI configurations.
-
-It requires Python 2.6, 2.7 or Python 3 and works with PyPy.
+contact data (MeCard, vCard) or WIFI configurations.
 
 
 Installation
@@ -54,7 +56,7 @@ Library
     >>> qr.version
     2
     >>> qr.error
-    'M'
+    '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
@@ -100,10 +102,9 @@ All factory functions use the same parameters to specify the desired error
 level, version, data mask etc., see `Segno's documentation`_ for details.
 
 
-Other QR Code generators
-------------------------
-* <https://pypi.python.org/pypi/PyQRCode/>
-* <https://pypi.python.org/pypi/qrcode/>
-* <https://pypi.python.org/pypi/qrcodegen/>
+Documentation
+-------------
+Read the online documentation at <https://segno.readthedocs.io/>
+
 
-.. _Segno's documentation: http://segno.readthedocs.io/en/latest/
+.. _Segno's documentation: https://segno.readthedocs.io/

docs/api-low-level.rst

@@ -10,7 +10,7 @@ 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 idependent of the :py:mod:`segno.encoder`
+:py:mod:`segno.writers` is independent of the :py:mod:`segno.encoder`
 module and vice versa.
 
 

docs/command-line.rst

@@ -45,7 +45,7 @@ Micro QR Code::
 Error correction level
 ^^^^^^^^^^^^^^^^^^^^^^
 
-The default error correction level is "M", use the ``error`` parameter to change
+The default error correction level is "L", use the ``error`` parameter to change
 it::
 
     $ segno "Ain't no grave" --error=q

docs/comparison-qrcode-libs.rst

@@ -26,7 +26,8 @@ Find maximal error correction level             No                    No
 `SVG`_ output                                   Yes                   Yes                    Yes                   Yes
 `EPS`_ output                                   Yes                   Yes                    No                    Yes
 `PDF`_ output                                   Yes                   No                     No                    Yes
-`XPM`_ output                                   No                    Yes                    No                    No
+`XBM`_ output                                   No                    Yes                    No                    Yes
+`XPM`_ output                                   No                    No                     No                    Yes
 `PBM`_ output                                   Yes                   No                     No                    Yes
 `PAM`_ output                                   No                    No                     No                    Yes
 `LaTeX`_ support                                No                    No                     No                    Yes
@@ -98,7 +99,8 @@ Create a QR Code 1-M "QR Code Symbol" and serialize it as PNG image.
 .. _SVG: https://en.wikipedia.org/wiki/Scalable_Vector_Graphics
 .. _EPS: https://en.wikipedia.org/wiki/Encapsulated_PostScript
 .. _PDF: https://en.wikipedia.org/wiki/Portable_Document_Format
-.. _XPM: https://en.wikipedia.org/wiki/X_PixMap
+.. _XBM: https://en.wikipedia.org/wiki/X_BitMap
+.. _XPM: https://de.wikipedia.org/wiki/X_PixMap
 .. _PBM: https://en.wikipedia.org/wiki/Netpbm_format
 .. _PAM: https://en.wikipedia.org/wiki/Netpbm#PAM_graphics_format
 .. _LaTeX: https://en.wikipedia.org/wiki/LaTeX

docs/make.rst

@@ -62,7 +62,7 @@ of QR Codes or Micro QR Codes: :py:func:`segno.make_qr` for QR Codes and
     'M4-M'
     >>> qr = segno.make_qr('The Beatles')  # Same content but as QR Code
     >>> qr.designator
-    '1-M'
+    '1-Q'
 
 
 If the provided content is too large, a :py:class:`segno.DataOverflowError` is thrown:
@@ -97,7 +97,7 @@ It's possible to specify the desired version for the provided ``content``.
 Error Correction Level
 ----------------------
 
-By default, Segno uses the error correction level "M" to encode the (Micro) QR
+By default, Segno uses the error correction level "L" to encode the (Micro) QR
 Code. Use the parameter ``error`` to change the error correction level.
 The ``error`` parameter is case-insensitive; to specify the error correction
 level "L", "l" and "L" are valid values. Available error correction levels are

docs/special-qrcode-factories.rst

@@ -4,7 +4,7 @@ Special QR Code factory functions
 The ``helpers`` module provides factory functions to create common QR Codes
 for encoding WIFI configurations, MeCards or geographic locations.
 
-The created QR Codes use at minimum the error correction level "M". If a better
+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
 better error correction level will be used.
 
@@ -14,10 +14,10 @@ Create a QR Code for a WIFI configuration
 .. code-block:: python
 
     >>> from segno import helpers
-    >>> # Create a WIFI config with min. error level "M" or better
+    >>> # Create a WIFI config with min. error level "L" or better
     >>> qr = helpers.make_wifi(ssid='My network', password='secret', security='WPA')
     >>> qr.designator
-    '3-Q'
+    '3-M'
 
 
 If you want more control over the creation of the QR Code (i.e. using a specific
@@ -46,7 +46,7 @@ Create a QR Code encoding geographic information
     >>> latitude, longitude = 38.8976763,-77.0365297
     >>> qr = helpers.make_geo(latitude, longitude)
     >>> qr.designator
-    '2-Q'
+    '2-M'
 
 A factory function for encoding the geographic information as string is also
 available.
@@ -68,6 +68,9 @@ available.
 Creating a QR Code encoding contact information
 -----------------------------------------------
 
+MeCard
+^^^^^^
+
 The function ``make_mecard`` returns a QR Code which encodes contact information
 as MeCard.
 
@@ -76,7 +79,7 @@ as MeCard.
     >>> from segno import helpers
     >>> qr = helpers.make_mecard(name='Doe,John', email='me@example.org', phone='+1234567')
     >>> qr.designator
-    '4-Q'
+    '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')
@@ -92,4 +95,34 @@ A factory function which returns the MeCard as string is available as well.
     'MECARD:N:Doe,John;TEL:+1234567;EMAIL:me@example.org;;'
     >>> qr = segno.make(mecard, error='H')
     >>> qr.designator
-    '6-H'
+    '6-H'
+
+
+vCard
+^^^^^
+
+The function ``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'

segno/__init__.py

@@ -1,6 +1,6 @@
 # -*- coding: utf-8 -*-
 #
-# Copyright (c) 2016 -- Lars Heuer - Semagia <http://www.semagia.com/>.
+# Copyright (c) 2016 - 2017 -- Lars Heuer - Semagia <http://www.semagia.com/>.
 # All rights reserved.
 #
 # License: BSD License
@@ -9,10 +9,6 @@
 QR Code and Micro QR Code implementation.
 
 "QR Code" and "Micro QR Code" are registered trademarks of DENSO WAVE INCORPORATED.
-
-:author:       Lars Heuer (heuer[at]semagia.com)
-:organization: Semagia - http://www.semagia.com/
-:license:      BSD License
 """
 from __future__ import absolute_import, unicode_literals
 import sys
@@ -21,13 +17,17 @@
     VersionError, DataOverflowError
 from . import writers, utils
 
-__version__ = '0.2.3'
+__version__ = '0.2.4'
 
 __all__ = ('make', 'make_qr', 'make_micro', 'QRCode', 'QRCodeError',
            'ErrorLevelError', 'ModeError', 'MaskError', 'VersionError',
            'DataOverflowError')
 
 
+# <https://wiki.python.org/moin/PortingToPy3k/BilingualQuickRef#New_Style_Classes>
+__metaclass__ = type
+
+
 def make(content, error=None, version=None, mode=None, mask=None, encoding=None,
          eci=False, micro=None, boost_error=True):
     """\
@@ -44,18 +44,18 @@ def make(content, error=None, version=None, mode=None, mask=None, encoding=None,
             used to specify the used encoding.
     :type content: str, int, bytes
     :param error: Error correction level. If ``None`` (default), error
-            correction level ``M`` is used (note: Micro QR Code version M1 does
+            correction level ``L`` is used (note: Micro QR Code version M1 does
             not support error correction. If an explicit error level is used,
             a M1 QR Code won't be generated).
             Valid values: ``None`` (allowing generation of M1 codes or use error
-            correction level "M"), "L", "M", "Q", "H" (error correction level
-            "H" isn't available for Micro QR Codes).
+            correction level "L" or better see ``boost_error``), "L", "M", "Q",
+            "H" (error correction level "H" isn't available for Micro QR Codes).
 
             =====================================   ===========================
             Error correction level                  Error correction capability
             =====================================   ===========================
-            L                                       recovers  7% of data
-            M (Segno's default unless version M1)   recovers 15% of data
+            L (Segno's default unless version M1)   recovers  7% of data
+            M                                       recovers 15% of data
             Q                                       recovers 25% of data
             H (not available for Micro QR Codes)    recovers 30% of data
             =====================================   ===========================
@@ -66,13 +66,13 @@ def make(content, error=None, version=None, mode=None, mask=None, encoding=None,
             The `error` parameter is case insensitive.
 
             See also the `boost_error` parameter.
-    :type error: str or None
+    :type error: str, unicode or None
     :param version: QR Code version. If the value is ``None`` (default), the
             minimal version which fits for the input data will be used.
             Valid values: "M1", "M2", "M3", "M4" (for Micro QR Codes) or an
             integer between 1 and 40 (for QR Codes).
             The `version` parameter is case insensitive.
-    :type version: int, str or None.
+    :type version: int, str, unicode or None.
     :param mode: "numeric", "alphanumeric", "byte", or "kanji". If the value is
             ``None`` (default) the appropriate mode will automatically be
             determined.
@@ -90,7 +90,7 @@ def make(content, error=None, version=None, mode=None, mask=None, encoding=None,
 
             The `mode` parameter is case insensitive.
 
-    :type mode: unicode|str|None
+    :type mode: str, unicode, or None
     :param mask: Data mask. If the value is ``None`` (default), the
             appropriate data mask is choosen automatically. If the `mask`
             parameter if provided, this function may raise a :py:exc:`MaskError`
@@ -173,7 +173,7 @@ def make_micro(content, error=None, version=None, mode=None, mask=None,
                 encoding=encoding, micro=True, boost_error=boost_error)
 
 
-class QRCode(object):
+class QRCode:
     """\
     Represents a (Micro) QR Code.
     """
@@ -630,6 +630,31 @@ def save(self, out, kind=None, **kw):
         =============    ==============================================================
 
 
+        **X BitMap (XBM)**
+
+        =============    ==============================================================
+        Name             Description
+        =============    ==============================================================
+        kind             "xbm"
+        scale            integer
+        name             Name of the variable (default: "img")
+        =============    ==============================================================
+
+
+        **X PixMap (XPM)**
+
+        =============    ==============================================================
+        Name             Description
+        =============    ==============================================================
+        kind             "xpm"
+        scale            integer
+        color            Default: "#000" (black).
+        background       Default value ``#fff`` (white)
+                         ``None`` indicates a transparent background.
+        name             Name of the variable (default: "img")
+        =============    ==============================================================
+
+
         :param out: A filename or a writable file-like object with a
                 ``name`` attribute. Use the `kind` parameter if `out` is
                 a :py:class:`io.ByteIO` or :py:class:`io.StringIO` stream which