========
Treepoem
========
.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/treepoem/main.yml?branch=main&style=for-the-badge
:target: https://github.com/adamchainz/treepoem/actions?workflow=CI
.. image:: https://img.shields.io/pypi/v/treepoem.svg?style=for-the-badge
:target: https://pypi.org/project/treepoem/
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge
:target: https://github.com/psf/black
.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge
:target: https://github.com/pre-commit/pre-commit
:alt: pre-commit
A cleverly named, but very simple python barcode renderer wrapping the
BWIPP_ library and ``ghostscript`` command line tool.
----
**Improve your Django and Git skills** with `one of my books <https://adamj.eu/books/>`__.
----
Installation
============
Install from **pip**:
.. code-block:: sh
python -m pip install treepoem
Python 3.8 to 3.12 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.
There's a known issue with rendering on Ghostscript 9.22+ where images are
smeared. See
`GitHub Issue #124 <https://github.com/adamchainz/treepoem/issues/124>`_ and
its associated links for more details. Ghostscript merged a fix in version
9.26 and common barcodes seem to work from then on, though still with some
smearing.
You can check your Ghostscript version with:
.. code-block:: sh
gs --version
API
===
``generate_barcode(barcode_type: str, data: str | bytes, options: dict[str, str | bool] | None=None, *, scale: int = 2) -> Image``
----------------------------------------------------------------------------------------------------------------------------------
Generates a barcode and returns it as a `PIL Image object <https://pillow.readthedocs.io/en/stable/reference/Image.html#the-image-class>`__
``barcode_type`` is the name of the barcode type to generate (see below).
``data`` is a ``str`` or ``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.
``scale`` controls the output image size.
Use ``1`` for the smallest image and larger values for larger images.
For example, this generates a QR code image, and saves it to a file using |Image.save()|__:
.. |Image.save()| replace:: ``Image.save()``
__ https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.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 colouring, converting the ``Image`` object to monochrome (``image.convert("1")``) will likely reduce its file size.
``barcode_types: dict[str, BarcodeType]``
-----------------------------------------
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.
Updating BWIPP
==============
For development of treepoem, when there's a new BWIPP release:
1. Run ``./download_bwipp.py`` with the version of BWIPP to download.
2. Run ``./make_data.py`` to update the barcode types that treepoem knows about.
3. Add a note in ``CHANGELOG.rst`` about the upgrade, adapting from the previous one.
4. Commit and make a pull request, `adapting from previous examples <https://github.com/adamchainz/treepoem/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aclosed+upgrade+bwipp>`__.
.. _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
Raw data
{
"_id": null,
"home_page": "",
"name": "treepoem",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "Adam Johnson <me@adamj.eu>",
"keywords": "barcode bwipp postscript ghostscript qr qrcode aztec azteccode pdf417 interleaved2of5 i25 code128 code39",
"author": "",
"author_email": "Christian Muirhead <xtian@babbageclunk.com>",
"download_url": "https://files.pythonhosted.org/packages/67/c4/f94385e9486eb6b24d65a948125275f8be269f07a226771af6531014e677/treepoem-3.24.0.tar.gz",
"platform": null,
"description": "========\nTreepoem\n========\n\n.. image:: https://img.shields.io/github/actions/workflow/status/adamchainz/treepoem/main.yml?branch=main&style=for-the-badge\n :target: https://github.com/adamchainz/treepoem/actions?workflow=CI\n\n.. image:: https://img.shields.io/pypi/v/treepoem.svg?style=for-the-badge\n :target: https://pypi.org/project/treepoem/\n\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg?style=for-the-badge\n :target: https://github.com/psf/black\n\n.. image:: https://img.shields.io/badge/pre--commit-enabled-brightgreen?logo=pre-commit&logoColor=white&style=for-the-badge\n :target: https://github.com/pre-commit/pre-commit\n :alt: pre-commit\n\nA cleverly named, but very simple python barcode renderer wrapping the\nBWIPP_ library and ``ghostscript`` command line tool.\n\n----\n\n**Improve your Django and Git skills** with `one of my books <https://adamj.eu/books/>`__.\n\n----\n\nInstallation\n============\n\nInstall from **pip**:\n\n.. code-block:: sh\n\n python -m pip install treepoem\n\nPython 3.8 to 3.12 supported.\n\nYou'll also need Ghostscript installed. On Ubuntu/Debian this can be installed\nwith:\n\n.. code-block:: sh\n\n apt-get install ghostscript\n\nOn Mac OS X use:\n\n.. code-block:: sh\n\n brew install ghostscript\n\nOtherwise refer to your distribution's package manager, though it's likely to\nbe called ``ghostscript`` too.\n\nThere's a known issue with rendering on Ghostscript 9.22+ where images are\nsmeared. See\n`GitHub Issue #124 <https://github.com/adamchainz/treepoem/issues/124>`_ and\nits associated links for more details. Ghostscript merged a fix in version\n9.26 and common barcodes seem to work from then on, though still with some\nsmearing.\n\nYou can check your Ghostscript version with:\n\n.. code-block:: sh\n\n gs --version\n\nAPI\n===\n\n``generate_barcode(barcode_type: str, data: str | bytes, options: dict[str, str | bool] | None=None, *, scale: int = 2) -> Image``\n----------------------------------------------------------------------------------------------------------------------------------\n\nGenerates a barcode and returns it as a `PIL Image object <https://pillow.readthedocs.io/en/stable/reference/Image.html#the-image-class>`__\n\n``barcode_type`` is the name of the barcode type to generate (see below).\n\n``data`` is a ``str`` or ``bytes`` of data to embed in the barcode - the amount\nthat can be embedded varies by type.\n\n``options`` is a dictionary of strings-to-strings of extra options to be passed\nto BWIPP_, as per its docs.\n\n``scale`` controls the output image size.\nUse ``1`` for the smallest image and larger values for larger images.\n\nFor example, this generates a QR code image, and saves it to a file using |Image.save()|__:\n\n.. |Image.save()| replace:: ``Image.save()``\n__ https://pillow.readthedocs.io/en/stable/reference/Image.html#PIL.Image.Image.save\n\n.. code-block:: python\n\n import treepoem\n\n image = treepoem.generate_barcode(\n barcode_type=\"qrcode\", # One of the BWIPP supported codes.\n data=\"barcode payload\",\n )\n image.convert(\"1\").save(\"barcode.png\")\n\nIf your barcode image is monochrome, with no additional text or colouring, converting the ``Image`` object to monochrome (``image.convert(\"1\")``) will likely reduce its file size.\n\n``barcode_types: dict[str, BarcodeType]``\n-----------------------------------------\n\nThis is a ``dict`` of the ~100 names of the barcode types that the vendored\nversion of BWIPP_ supports: its keys are ``str``\\s of the barcode type encoder\nnames, and the values are instances of ``BarcodeType``.\n\n``BarcodeType``\n---------------\n\nA class representing meta information on the types. It has two attributes:\n\n* ``type_code`` - the value needed for the ``barcode_type`` argument of\n ``generate_barcode()`` to use this type.\n\n* ``description`` - the human level description of the type\n which has two ``str``.\n\nOnly these common types are used in the test suite:\n\n* ``qrcode`` - `QR Code`_\n\n* ``azteccode`` - `Aztec Code`_\n\n* ``pdf417`` - PDF417_\n\n* ``interleaved2of5`` - `Interleaved 2 of 5`_\n\n* ``code128`` - `Code 128`_\n\n* ``code39`` - `Code 39`_\n\nCommand-line interface\n======================\n\nTreepoem also includes a simple command-line interface to the\nfunctionality of ``generate_barcode``. For example, these commands\nwill generate two QR codes with identical contents, but different levels\nof error correction (see `QR Code Options`_):\n\n.. code-block:: sh\n\n $ treepoem -o barcode1.png -t qrcode \"This is a test\" eclevel=H\n $ treepoem -o barcode2.png -t qrcode \"^084his is a test\" eclevel=L parse\n\nComplete usage instructions are shown with ``treepoem --help``.\n\nWhat's so clever about the name?\n================================\n\nBarcode.\n\nBark ode.\n\nTree poem.\n\nUpdating BWIPP\n==============\n\nFor development of treepoem, when there's a new BWIPP release:\n\n1. Run ``./download_bwipp.py`` with the version of BWIPP to download.\n2. Run ``./make_data.py`` to update the barcode types that treepoem knows about.\n3. Add a note in ``CHANGELOG.rst`` about the upgrade, adapting from the previous one.\n4. Commit and make a pull request, `adapting from previous examples <https://github.com/adamchainz/treepoem/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aclosed+upgrade+bwipp>`__.\n\n.. _BWIPP: https://github.com/bwipp/postscriptbarcode\n.. _QR Code: https://github.com/bwipp/postscriptbarcode/wiki/QR-Code\n.. _Aztec Code: https://github.com/bwipp/postscriptbarcode/wiki/Aztec-Code\n.. _PDF417: https://github.com/bwipp/postscriptbarcode/wiki/PDF417\n.. _Interleaved 2 of 5: https://github.com/bwipp/postscriptbarcode/wiki/Interleaved-2-of-5\n.. _Code 128: https://github.com/bwipp/postscriptbarcode/wiki/Code-128\n.. _Code 39: https://github.com/bwipp/postscriptbarcode/wiki/Code-39\n.. _QR Code Options: https://github.com/bwipp/postscriptbarcode/wiki/QR-Code\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Barcode rendering for Python supporting QRcode, Aztec, PDF417, I25, Code128, Code39 and many more types.",
"version": "3.24.0",
"project_urls": {
"Changelog": "https://github.com/adamchainz/treepoem/blob/main/CHANGELOG.rst",
"Funding": "https://adamj.eu/books/",
"Repository": "https://github.com/adamchainz/treepoem"
},
"split_keywords": [
"barcode",
"bwipp",
"postscript",
"ghostscript",
"qr",
"qrcode",
"aztec",
"azteccode",
"pdf417",
"interleaved2of5",
"i25",
"code128",
"code39"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3fa4a4a311e85e668cdbddb875c7a9276dafe8aee3c808ecfd56996eee56baa6",
"md5": "2af57399c474276ee5bfbfbd8c365cf9",
"sha256": "aab140eff462887290f581cb72adf68485955dd01382ecfadf95861a537bd222"
},
"downloads": -1,
"filename": "treepoem-3.24.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "2af57399c474276ee5bfbfbd8c365cf9",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 359418,
"upload_time": "2024-03-11T22:26:46",
"upload_time_iso_8601": "2024-03-11T22:26:46.247170Z",
"url": "https://files.pythonhosted.org/packages/3f/a4/a4a311e85e668cdbddb875c7a9276dafe8aee3c808ecfd56996eee56baa6/treepoem-3.24.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "67c4f94385e9486eb6b24d65a948125275f8be269f07a226771af6531014e677",
"md5": "ddc808c92d4e73dc7c02ff29763b667b",
"sha256": "ec59787899c338f4d65ad26411b526b00c420561319d5b1b757239b5afb1530e"
},
"downloads": -1,
"filename": "treepoem-3.24.0.tar.gz",
"has_sig": false,
"md5_digest": "ddc808c92d4e73dc7c02ff29763b667b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 362439,
"upload_time": "2024-03-11T22:26:48",
"upload_time_iso_8601": "2024-03-11T22:26:48.455389Z",
"url": "https://files.pythonhosted.org/packages/67/c4/f94385e9486eb6b24d65a948125275f8be269f07a226771af6531014e677/treepoem-3.24.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-11 22:26:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "adamchainz",
"github_project": "treepoem",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "treepoem"
}
JSON
