caretly

Python client for the Caretly API: render ZPL labels to PDF or PNG.

• Sync (caretly.Client) and asyncio (caretly.AsyncClient) clients with the same API.
• One dependency: httpx.
• Typed (py.typed), Python 3.9+.
• Retries rate limits (429), overload (503) and connection errors, with an Idempotency-Key so a retry is never billed twice.

Install

pip install caretly

Quickstart

Create an API key in the console. Live keys start with zpl_live_, test keys with zpl_test_ (test keys are free and watermark every label).

import caretly

client = caretly.Client(api_key="zpl_test_...")  # or set CARETLY_API_KEY

result = client.render("^XA^FO50,50^A0N,50,50^FDHello^FS^XZ")
result.save("label.pdf")
print(result.page_count, result.labels_billed)

png = client.render("^XA^FO50,50^A0N,50,50^FDHello^FS^XZ", format="png", dpmm=12)
png.save("label.png")

Several files in one request, each with a fresh printer state, pages in upload order:

result = client.render_files({"order-1.zpl": zpl_1, "order-2.zpl": zpl_2})
print(result.file_page_counts)  # (2, 1)

files is a mapping of name to content, or a sequence of (name, content) pairs. Content is str (sent as UTF-8) or bytes.

Async:

import asyncio
import caretly


async def main() -> None:
    async with caretly.AsyncClient() as client:
        result = await client.render("^XA^FDHello^FS^XZ")
        result.save("label.pdf")


asyncio.run(main())

Close the client when done (client.close() / await client.aclose()), or use it as a (async) context manager.

Client options

Render options

render(zpl, ...) and render_files(files, ...) take these keyword arguments:

page and dpmm are checked before sending and raise ValueError when out of range.

render_pdf(zpl, ...) and render_png(zpl, page=None, ...) are shorthands.

Result

RenderResult is a frozen dataclass:

result.save(path) writes content to a file and returns the pathlib.Path.

client.health() returns True when GET /health answers ok, False for any other response, and raises APIConnectionError when the server cannot be reached.

Errors

All errors derive from caretly.CaretlyError.

APIError has status_code, message (the server's plain-text explanation), retry_after (seconds, or None) and response (the httpx.Response).

try:
    client.render(zpl)
except caretly.BadRequestError as e:
    print("Fix the label:", e.message)
except caretly.APIError as e:
    print(e.status_code, e.message)

Retries

429 and 503 responses and connection errors are retried up to max_retries times (default 2). Timeouts are not retried: APITimeoutError is raised on the first one. The client waits Retry-After seconds when the server sends it, else 0.5 s, 1 s, 2 s, ... up to 8 s. Other statuses are not retried. Set max_retries=0 to turn retries off.

Development

python -m venv .venv
.venv/bin/pip install -e . --group dev   # pip >= 25.1
.venv/bin/pytest
.venv/bin/mypy --strict src
.venv/bin/ruff check . && .venv/bin/ruff format --check .

Publishing

1. Bump __version__ in src/caretly/_version.py and add a CHANGELOG.md entry.

2. Build and check:

   rm -rf dist
   .venv/bin/python -m build
   .venv/bin/twine check dist/*
   

3. Optionally try TestPyPI first: .venv/bin/twine upload --repository testpypi dist/*.

4. Upload: .venv/bin/twine upload dist/* (with a PyPI API token as password, user __token__), or set up trusted publishing.

5. Tag the release, e.g. git tag clients/python/v0.1.0 && git push origin clients/python/v0.1.0.

Links

• Caretly: https://caretly.dev
• Source: https://github.com/jaapieaapie1/zpl (this client lives in clients/python)

License

MIT, see LICENSE.