Metadata-Version: 2.1
Name: treepoem
Version: 3.0.0
Summary: Barcode rendering for Python 2 and 3 supporting QRcode, Aztec, PDF417, I25, Code128, Code39 and many more types.
Home-page: https://github.com/adamchainz/treepoem
Author: Christian Muirhead
Author-email: xtian@babbageclunk.com
Maintainer: Adam Johnson
Maintainer-email: me@adamj.eu
License: MIT
Keywords: barcode bwipp postscript ghostscript qr qrcode aztec azteccode pdf417 interleaved2of5 i25 code128 code39
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Requires-Python: >=3.4
Requires-Dist: Pillow

========
Treepoem
========

.. image:: https://img.shields.io/pypi/v/treepoem.svg
           :target: https://pypi.python.org/pypi/treepoem

.. image:: https://img.shields.io/travis/adamchainz/treepoem.svg
           :target: https://travis-ci.org/adamchainz/treepoem


A cleverly named, but very simple python barcode renderer wrapping the
BWIPP_ library and ``ghostscript`` command line tool.

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

Install from **pip**:

.. code-block:: sh

    pip install treepoem

Python 3.4+ supported.

You'll also need Ghostscript installed. On Ubuntu/Debian this can be installed
with:

.. code-block:: sh

    apt-get install ghostscript

On Mac OS X use:

.. code-block:: sh

    brew install ghostscript

Otherwise refer to your distribution's package manager, though it's likely to
be called ``ghostscript`` too.

---
API
---

``generate_barcode(barcode_type, data, options=None)``
------------------------------------------------------

Generates a barcode and returns it as a PIL image file object (specifically, a
``PIL.EpsImagePlugin.EpsImageFile``).

``barcode_type`` is the name of the barcode type to generate (see below).

``data`` is a ``str`` (Python 2 ``unicode``) or ``bytes`` (Python 2 ``bytes``)
of data to embed in the barcode - the amount that can be embedded varies by
type.

``options`` is a dictionary of strings-to-strings of extra options to be passed
to BWIPP_, as per its docs.

For example, this generates a QR code image, and saves it to a file using
standard PIL ``Image.save()``:

.. code-block:: python

   >>> import treepoem
   >>> image = treepoem.generate_barcode(
   ...     barcode_type='qrcode',  # One of the BWIPP supported codes.
   ...     data='barcode payload',
   ... )
   >>> image.convert('1').save('barcode.png')

If your barcode image is monochrome, with no additional text or
coloring, converting the ``Image`` object to monochrome as shown above
(``image.convert('1')``) will likely reduce its file size.

``barcode_types``
-----------------

This is a ``dict`` of the ~100 names of the barcode types that the vendored
version of BWIPP_ supports: its keys are ``str``\s of the barcode type encoder
names, and the values are instances of ``BarcodeType``.

``BarcodeType``
---------------

A class representing meta information on the types. It has two attributes:

* ``type_code`` - the value needed for the ``barcode_type`` argument of
  ``generate_barcode()`` to use this type.

* ``description`` - the human level description of the type
  which has two ``str``.

Only these common types are used in the test suite:

* ``qrcode`` - `QR Code`_

* ``azteccode`` - `Aztec Code`_

* ``pdf417`` - PDF417_

* ``interleaved2of5`` - `Interleaved 2 of 5`_

* ``code128`` - `Code 128`_

* ``code39`` - `Code 39`_

----------------------
Command-line interface
----------------------

Treepoem also includes a simple command-line interface to the
functionality of ``generate_barcode``. For example, these commands
will generate two QR codes with identical contents, but different levels
of error correction (see `QR Code Options`_):

.. code-block:: sh

   $ treepoem -o barcode1.png -t qrcode "This is a test" eclevel=H
   $ treepoem -o barcode2.png -t qrcode "^084his is a test" eclevel=L parse

Complete usage instructions are shown with ``treepoem --help``.

--------------------------------
What's so clever about the name?
--------------------------------

Barcode.

Bark ode.

Tree poem.


.. _BWIPP: https://github.com/bwipp/postscriptbarcode
.. _QR Code: https://github.com/bwipp/postscriptbarcode/wiki/QR-Code
.. _Aztec Code: https://github.com/bwipp/postscriptbarcode/wiki/Aztec-Code
.. _PDF417: https://github.com/bwipp/postscriptbarcode/wiki/PDF417
.. _Interleaved 2 of 5: https://github.com/bwipp/postscriptbarcode/wiki/Interleaved-2-of-5
.. _Code 128: https://github.com/bwipp/postscriptbarcode/wiki/Code-128
.. _Code 39: https://github.com/bwipp/postscriptbarcode/wiki/Code-39
.. _QR Code Options: https://github.com/bwipp/postscriptbarcode/wiki/QR-Code




-------
History
-------

.. Insert new release notes below this line

3.0.0 (2019-05-08)
------------------

* Drop Python 2 support, only Python 3.4+ is supported now.
* Upgrade BWIPP from 2017-05-20 to 2018-07-27. This has a few bug fixes and
  performance improvements. You can read its changelog in the vendored copy in
  the `treepoem repo
  <https://github.com/adamchainz/treepoem/blob/master/treepoem/postscriptbarcode/CHANGES>`__.

2.0.0 (2018-08-04)
------------------

* Support binary barcode data - if ``bytes`` (``str`` on Python 2) is passed
  as data, it's not encoded. This has introduced a dependency on ``six``. This
  may be backwards incompatible, depending on what type of data you're passing
  in on Python 2.
* Make ``treepoem.barcode_types`` a ``dict`` mapping the BWIPP encoder
  names to a custom type containing a human-readable ``description``. This is
  backwards incompatible if you're relying on ``barcode_types`` which
  previously was a ``set`` of the encoder names.
* Upgrade BWIPP from 2017-10-19 to 2018-05-20. This has a few bug fixes and
  performance improvements. You can read its changelog in the vendored copy in
  the `treepoem repo
  <https://github.com/adamchainz/treepoem/blob/master/treepoem/postscriptbarcode/CHANGES>`__.

1.4.1 (2018-05-01)
------------------

* Fix formatting bug in CLI output.

1.4.0 (2018-05-01)
------------------

* Make the ``options`` argument to ``generate_barcode`` optional.
* Add a CLI ``treepoem``.
* Upgrade BWIPP from 2017-07-10 to 2017-10-19. This has a few bug fixes and
  performance improvements. You can read its changelog in the vendored copy in
  the `treepoem repo
  <https://github.com/adamchainz/treepoem/blob/master/treepoem/postscriptbarcode/CHANGES>`__.

1.3.2 (2017-10-22)
------------------

* Upgrade BWIPP from 2017-07-10 to 2017-10-19. This has a few bug fixes. You
  can read its changelog in the vendored copy in the `treepoem repo
  <https://github.com/adamchainz/treepoem/blob/master/treepoem/postscriptbarcode/CHANGES>`__.

1.3.1 (2017-08-24)
------------------

* Upgrade BWIPP from 2017-06-20 to 2017-07-10. This has a few bug fixes. You
  can read its changelog in the vendored copy in the `treepoem repo
  <https://github.com/adamchainz/treepoem/blob/master/treepoem/postscriptbarcode/CHANGES>`__.

1.3.0 (2017-06-21)
------------------

* Upgrade BWIPP from 2015-11-24 to 2017-06-20. This has a number of bug fixes,
  and supports more barcode types. It has also changed the pixel-for-pixel
  output of some formats, although they still encode the same information -
  notably QR codes, which are tested in ``treepoem``\'s test suite. You can
  read its changelog in the `vendored copy in the treepoem repo
  <https://github.com/adamchainz/treepoem/blob/master/treepoem/postscriptbarcode/CHANGES>`__.

1.2.0 (2017-06-21)
------------------

* Add ``treepoem.barcode_types``, a set of all the names of supported barcode
  types, and error if asked to generate a barcode of an unknown type.

1.1.0 (2017-04-13)
------------------

* Support Windows.

1.0.1 (2016-03-30)
------------------

* Add the missing ``BWIPP`` files.

1.0.0 (2016-03-23)
------------------

* Use ``$PATH`` to find ``gs`` binary.
* Rename ``PostscriptError`` to ``TreepoemError``.
* Add basic ``setup.py``.
* Setup Travis CI build.
* Setup Tox


