Metadata-Version: 2.4
Name: segno
Version: 1.6.0
Summary: QR Code and Micro QR Code generator for Python
Author-email: Lars Heuer <heuer@semagia.com>
License: Copyright (c) 2016 - 2023, Lars Heuer
        All rights reserved.
        
        Redistribution and use in source and binary forms, with or without modification,
        are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice,
           this list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice,
           this list of conditions and the following disclaimer in the documentation
           and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its contributors
           may be used to endorse or promote products derived from this software
           without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
        ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
        WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
        DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
        FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
        DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
        SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
        CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
        OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
        OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
        
Project-URL: Homepage, https://github.com/heuer/segno/
Project-URL: Documentation, https://segno.readthedocs.io/
Project-URL: Issue tracker, https://github.com/heuer/segno/issues/
Project-URL: Changes, https://github.com/heuer/segno/blob/master/CHANGES.rst
Keywords: QR Code,Micro QR Code,ISO/IEC 18004,ISO/IEC 18004:2006(E),ISO/IEC 18004:2015(E),qrcode,QR,barcode,matrix,2D
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Multimedia :: Graphics
Classifier: Topic :: Printing
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Requires-Python: >=3.5
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: importlib-metadata>=3.6.0; python_version < "3.10"
Dynamic: license-file

QR Code encoder and Micro QR Code encoder
=========================================

Pure Python QR Code generator with no dependencies.

This package implements ISO/IEC 18004:2015(E) "QR Code bar code symbology
specification" and produces QR Codes and Micro QR Codes with nearly no effort.
It supports the `Structured Append mode <https://segno.readthedocs.io/en/stable/structured-append.html>`_
which splits a message across several QR codes.

Segno (Italian for "sign" / "symbol") provides several serialization formats
like Scalable Vector Graphics (SVG), Encapsulated PostScript (EPS),
Portable Network Graphics (PNG), Portable Document Format (PDF), Netpbm (PAM, PBM, PPM),
LaTeX (PGF/TikZ), X PixMap (XBM), and 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 (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 QR Codes <https://segno.readthedocs.io/en/stable/special-qrcode-factories.html#create-a-qr-code-for-a-wifi-configuration>`_.

The project provides more than 1500 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 QR Code generator 
* No dependencies
* 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
* `Structured Append mode <https://segno.readthedocs.io/en/stable/structured-append.html>`_
* `Hanzi mode <https://segno.readthedocs.io/en/stable/qrcode-modes.html#hanzi-mode>`_
* `Command line interface <https://segno.readthedocs.io/en/stable/command-line.html>`_
* `Simple, user-friendly API <https://segno.readthedocs.io/en/stable/make.html>`_

.. code-block:: python

    import segno
    qrcode = segno.make('Yellow Submarine')
    qrcode.save('yellow-submarine.png')

* `Colorful QR codes <https://segno.readthedocs.io/en/stable/colorful-qrcodes.html>`_

  .. image:: https://github.com/heuer/segno/raw/master/docs/_static/colorful/qrcode_yellow-submarine.png
    :alt: Colorful 7-H QR code encoding "Yellow Submarine"

  ... works also with Micro QR codes

  .. image:: https://github.com/heuer/segno/raw/master/docs/_static/colorful/micro_qrcode_rain.png
    :alt: Colorful M4-Q Micro QR code encoding "Rain"

* `Artistic QR Codes <https://segno.readthedocs.io/en/stable/artistic-qrcodes.html>`_
  (requires the `qrcode-artistic <https://github.com/heuer/qrcode-artistic>`_ plug-in)

  .. image:: https://github.com/heuer/segno/raw/master/docs/_static/artistic/letitbe.jpg
    :alt: Animated 3-H QR code encoding "The Beatles -- Let It Be"

  ... animated QR codes are supported as well

  .. image:: https://github.com/heuer/segno/raw/master/docs/_static/artistic/abbey-road.webp
    :alt: Animated 4-H QR code encoding "The Beatles -- Abbey Road"


Installation
------------

Use ``pip`` to install segno from PyPI::

    $ pip install segno


MacPorts
^^^^^^^^

Segno is also available at `MacPorts <https://www.macports.org/>`_
(`MacPorts project page <https://ports.macports.org/port/py-segno/>`_)::

    $ sudo port install py-segno


conda-forge
^^^^^^^^^^^

The library is also available at `conda-forge <https://conda-forge.org/>`_
(`conda-forge project page <https://anaconda.org/conda-forge/segno>`_)::

    $ conda install -c conda-forge segno


Debian 11 / Bullseye
^^^^^^^^^^^^^^^^^^^^

::

    $ apt-get install python3-segno


Debian 10 / Buster (backports)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

::

    $ apt-get -t buster-backports install python3-segno


Arch Linux
^^^^^^^^^^

::

    $ pacman -S python-segno



Usage
-----

Command line
^^^^^^^^^^^^

The command line script prints a QR code to the terminal::

    $ segno "Comfortably Numb"


To serialize a QR code, use the "output" argument::

    $ segno -o=raincoat.svg "Famous Blue Raincoat"
    $ 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"



Library
^^^^^^^

.. code-block:: python

    >>> import segno
    >>> # Let Segno choose the minimal version and an optimal (maximal) error
    >>> # level without changing the minimal version
    >>> qrcode = segno.make('Up Jumped the Devil')
    >>> qrcode.designator  # Returns the QR code version and the error correction level
    '2-Q'
    >>> qrcode.save('up-jumped-the-devil.png')  # Save as PNG
    >>> qrcode.save('up-jumped-the-devil-2.png', scale=10)  # Scaling factor 10
    >>> qrcode.save('up-jumped-the-devil-3.png', light=None)  # Transparent light modules
    >>> qrcode.save('up-jumped-the-devil.pdf', scale=10)  # Save as PDF
    >>> # SVG drawing the dark modules in "dark blue"
    >>> qrcode.save('up-jumped-the-devil.svg', scale=10, dark='darkblue')


If the content to encode is small enough, a Micro QR code is generated:

.. code-block:: python

    >>> import segno
    >>> qrcode = segno.make('RAIN')
    >>> qrcode.is_micro
    True
    >>> qrcode.designator
    'M2-M'


If this behaviour is not desired, the user may set ``micro`` to ``False``

.. code-block:: python

    >>> import segno
    >>> qrcode = segno.make('RAIN', micro=False)
    >>> qrcode.is_micro
    False
    >>> qrcode.designator
    '1-H'


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
    >>> qrcode_micro = segno.make_micro('THE BEATLES')
    >>> qrcode_micro.designator
    'M3-M'
    >>> qrcode = segno.make_qr('THE BEATLES')  # Same content but enforce a QR Code
    >>> qrcode.designator
    '1-Q'
    >>> # This won't work since the data does not fit into a Micro QR Code M1 - M4
    >>> micro_qrcode = segno.make_micro('Nick Cave and the Bad Seeds')
    Traceback (most recent call last):
        ...
    DataOverflowError: Data too large. No Micro QR Code can handle the provided data


All factory functions use the same parameters to specify the desired error
level, version, data mask etc., see `Segno's documentation`_ for details.


Documentation
-------------
Read the online documentation at <https://segno.readthedocs.io/>


Trademark
---------
"QR Code" and "Micro QR Code" are registered trademarks of DENSO WAVE INCORPORATED.


.. _Segno's documentation: https://segno.readthedocs.io/
