.. |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:
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) |
+-----------------------+--------------------------------------------------------------------------------------------------------------+
| string_line_break | Number of characters in graphic field content after which a line break is inserted (default None) |
+-----------------------+--------------------------------------------------------------------------------------------------------------+
| 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 |
+=======================+=======================================================================================================================+
| dpi | Pixels per PDF canvas unit, defines resolution scaling of the PDF image (<72: compress, >72: stretch, default 72) |
+-----------------------+-----------------------------------------------------------------------------------------------------------------------+
| split_pages | Split the PDF into separate ZPL labels for each page (True or False, default False) |
+-----------------------+-----------------------------------------------------------------------------------------------------------------------+
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 Librarypypdfium2 <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, string_line_break=80, 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, dpi=72, width=720, height=1280, pos_x=100, pos_y=100, rotation=90, string_line_break=80, 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)
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:
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>_.
.. image:: https://raw.githubusercontent.com/miikanissi/zebrafy/master/docs/zebrafy-long.png :alt: Zebrafy Logo
FAQs
Python library for converting PDF and images to Zebra Programming Language (ZPL)
We found that zebrafy demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
A flawed sandbox in @nestjs/devtools-integration lets attackers run code on your machine via CSRF, leading to full Remote Code Execution (RCE).
Product
Customize license detection with Socket’s new license overlays: gain control, reduce noise, and handle edge cases with precision.
Product
Socket now supports Rust and Cargo, offering package search for all users and experimental SBOM generation for enterprise projects.
