Metadata-Version: 2.1
Name: zebrafy
Version: 1.1.4
Summary: Python library for converting PDF and images to Zebra Programming Language (ZPL)
Author-email: Miika Nissi <miika@miikanissi.com>
Maintainer-email: Miika Nissi <miika@miikanissi.com>
License: LGPLv3
Project-URL: Homepage, https://github.com/miikanissi/zebrafy/
Project-URL: Documentation, https://zebrafy.readthedocs.io/
Classifier: Development Status :: 4 - Beta
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 (LGPLv3)
Classifier: Operating System :: OS Independent
Classifier: Natural Language :: English
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Intended Audience :: Manufacturing
Classifier: Topic :: Printing
Requires-Python: >=3.8
Description-Content-Type: text/x-rst
License-File: LICENSE.txt
Requires-Dist: pillow
Requires-Dist: pypdfium2>=4.8.0
Provides-Extra: docs
Requires-Dist: sphinx>=7.0.0; extra == "docs"
Requires-Dist: sphinx_autodoc_typehints>=2.0.0; extra == "docs"
Requires-Dist: sphinx_rtd_theme>=2.0.0; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: lint
Requires-Dist: pre-commit; extra == "lint"
Provides-Extra: build
Requires-Dist: setuptools>=64; extra == "build"
Requires-Dist: setuptools_scm>=8; extra == "build"
Requires-Dist: wheel; extra == "build"
Requires-Dist: build; extra == "build"

|zebrafy_icon_64| Zebrafy
=========================

.. |zebrafy_icon_64| image:: https://raw.githubusercontent.com/miikanissi/zebrafy/master/docs/zebrafy-64.png
   :alt: Zebrafy Logo

.. image:: https://github.com/miikanissi/zebrafy/actions/workflows/ci.yml/badge.svg
    :target: https://github.com/miikanissi/zebrafy/actions/workflows/ci.yml
    :alt: CI

.. image:: https://readthedocs.org/projects/zebrafy/badge/?version=latest
    :target: https://zebrafy.readthedocs.io/en/latest/?badge=latest
    :alt: Documentation Status

.. image:: https://img.shields.io/pypi/v/zebrafy
    :target: https://pypi.org/project/zebrafy
    :alt: Zebrafy PyPi Package

.. image:: https://img.shields.io/badge/license-LGPLv3-green
    :target: https://www.gnu.org/licenses/lgpl-3.0.en.html#license-text
    :alt: License

**Zebrafy** is a Python 3 library for converting PDF and images to and from
`Zebra Programming Language (ZPL) <https://en.wikipedia.org/wiki/Zebra_Programming_Language>`_
graphic fields (^GF).

**Zebrafy** consists of three conversion tools:

- **ZebrafyImage** — convert an image into valid ZPL
- **ZebrafyPDF** — convert a PDF into valid ZPL
- **ZebrafyZPL** — convert valid ZPL graphic fields into images or PDF

If you want more control over the resulting ZPL data, **ZebrafyImage** and
**ZebrafyPDF** support the following optional parameters:

+----------------------+--------------------------------------------------------------------------------------------------------------+
| Parameter            | Description                                                                                                  |
+======================+==============================================================================================================+
| ``format``           | ZPL graphic field format type (default ``"ASCII"``)                                                          |
|                      |                                                                                                              |
|                      | - ``"ASCII"`` — ASCII hexadecimal (most compatible)                                                          |
|                      | - ``"B64"`` — Base64 Binary                                                                                  |
|                      | - ``"Z64"`` — Z64 compressed binary (best compression)                                                       |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| ``invert``           | Invert the black and white in the image/PDF output. (``True`` or ``False``, default ``False``)               |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| ``dither``           | Dither the result instead of hard limit on black pixels. (``True`` or ``False``, default ``True``)           |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| ``threshold``        | Black pixel threshold for image without dithering (``0-255``, default ``128``)                               |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| ``width``            | Width of the image in the resulting ZPL, ``0`` to use original image/PDF width (default ``0``)               |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| ``height``           | Height of the image in the resulting ZPL, ``0`` to use original image/PDF height (default ``0``)             |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| ``pos_x``            | Pixel x position of the graphic field in resulting ZPL (default ``0``)                                       |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| ``pos_y``            | Pixel y position of the graphic field in resulting ZPL (default ``0``)                                       |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| ``rotation``         | Rotates the image by the specified degree (``0``, ``90``, ``180`` or ``270``, default ``0``)                 |
+----------------------+--------------------------------------------------------------------------------------------------------------+
| ``complete_zpl``     | Add ZPL header and footer or only get the ZPL graphic field output (``True`` or ``False``, default ``True``) |
+----------------------+--------------------------------------------------------------------------------------------------------------+

Additionally, **ZebrafyPDF** supports the following optional parameters:

+----------------------+--------------------------------------------------------------------------------------------------------------+
| Parameter            | Description                                                                                                  |
+======================+==============================================================================================================+
| ``split_pages``      | Split the PDF into separate ZPL labels for each page (``True`` or ``False``, default ``False``)              |
+----------------------+--------------------------------------------------------------------------------------------------------------+


Getting Started
---------------

Installation
^^^^^^^^^^^^

.. code-block:: console

  pip install zebrafy


Dependencies
^^^^^^^^^^^^

Pip handles all dependencies automatically. This library is built on top of:

- `Pillow <https://pillow.readthedocs.io/>`_ — Python Imaging Library
- `pypdfium2 <https://github.com/pypdfium2-team/pypdfium2>`_ — Python 3 binding to
  `PDFium <https://pdfium.googlesource.com/pdfium/+/refs/heads/main>`_

Example Usage
^^^^^^^^^^^^^

Image to ZPL Graphic Field with **ZebrafyImage**
""""""""""""""""""""""""""""""""""""""""""""""""

Convert image bytes into a complete ZPL string and save to file:

.. code-block:: python

  from zebrafy import ZebrafyImage

  with open("source.png", "rb") as image:
      zpl_string = ZebrafyImage(image.read()).to_zpl()

  with open("output.zpl", "w") as zpl:
      zpl.write(zpl_string)

Example usage with optional parameters:

.. code-block:: python

  from zebrafy import ZebrafyImage

  with open("source.png", "rb") as image:
      zpl_string = ZebrafyImage(
          image.read(),
          format="Z64",
          invert=True,
          dither=False,
          threshold=128,
          width=720,
          height=1280,
          pos_x=100,
          pos_y=100,
          rotation=90,
          complete_zpl=True,
      ).to_zpl()

  with open("output.zpl", "w") as zpl:
      zpl.write(zpl_string)

Alternatively, **ZebrafyImage** also accepts PIL Image as the image parameter instead of
image bytes:

.. code-block:: python

  from PIL import Image
  from zebrafy import ZebrafyImage

  pil_image = Image.new(mode="RGB", size=(100, 100))
  zpl_string = ZebrafyImage(pil_image).to_zpl()

  with open("output.zpl", "w") as zpl:
      zpl.write(zpl_string)


PDF to ZPL Graphic Field with **ZebrafyPDF**
""""""""""""""""""""""""""""""""""""""""""""

Convert PDF bytes into a complete ZPL string and save to file:

.. code-block:: python

  from zebrafy import ZebrafyPDF

  with open("source.pdf", "rb") as pdf:
      zpl_string = ZebrafyPDF(pdf.read()).to_zpl()

  with open("output.zpl", "w") as zpl:
      zpl.write(zpl_string)

**ZebrafyPDF** conversion supports the same optional parameters as **ZebrafyImage**
conversion, with the addition of the ``split_pages`` parameter to split the PDF pages:

.. code-block:: python

  from zebrafy import ZebrafyPDF

  with open("source.pdf", "rb") as pdf:
      zpl_string = ZebrafyPDF(
          pdf.read(),
          format="Z64",
          invert=True,
          dither=False,
          threshold=128,
          width=720,
          height=1280,
          pos_x=100,
          pos_y=100,
          rotation=90,
          complete_zpl=True,
          split_pages=True,
      ).to_zpl()

  with open("output.zpl", "w") as zpl:
      zpl.write(zpl_string)

ZPL to PDF or Images with **ZebrafyZPL**
""""""""""""""""""""""""""""""""""""""""

Convert all graphic fields from a valid ZPL file to PIL Images and save to image files:

.. code-block:: python

  from zebrafy import ZebrafyZPL

  with open("source.zpl", "r") as zpl:
      pil_images = ZebrafyZPL(zpl.read()).to_images()
      for count, pil_image in enumerate(pil_images):
          pil_image.save(f"output_{count}.png", "PNG")

Convert all graphic fields from a valid ZPL file to PDF bytes and save to PDF file:

.. code-block:: python

  from zebrafy import ZebrafyZPL

  with open("source.zpl", "r") as zpl:
      pdf_bytes = ZebrafyZPL(zpl.read()).to_pdf()

  with open("output.pdf", "wb") as pdf:
      pdf.write(pdf_bytes)


Contributing and Issues
-----------------------

Contributions and bug reports are welcome and can be submitted on the
`GitHub page <https://github.com/miikanissi/zebrafy>`_.

The project does not yet have a well-defined scope, and I'm open to new feature
requests. Features currently in consideration are:

- HTML to ZPL conversion by implementing standard HTML elements into ZPL commands
- Extract text from a PDF to render it as a native ZPL command instead of graphic field

License
-------

This source is released under the
`GNU Lesser General Public License v3.0 <https://www.gnu.org/licenses/lgpl-3.0.en.html#license-text>`_.

Logo
----

.. image:: https://raw.githubusercontent.com/miikanissi/zebrafy/master/docs/zebrafy-long.png
   :alt: Zebrafy Logo
