pdf4me

Python client for the PDF4me API. Convert, optimize, merge, split, stamp, and extract content from documents with async functions and typed results.

Requires Python 3.11 or newer and a PDF4me API key.

Upgrading from 0.8.x? Version 1.0 is a rewrite and nothing from 0.8.x keeps working. See Migrating from 0.8.x.

Installation

python -m pip install pdf4me

To install from a source checkout, run python -m pip install . in this package directory. The import name is pdf4me.

Quick start

Set your API key in the environment:

export PDF4ME_API_KEY="your-api-key"

Save this as optimize_pdf.py and put an input.pdf in the same working directory. The example uploads the PDF for optimization and saves the result as optimized.pdf.

import asyncio
import os
from pathlib import Path

from pdf4me import Pdf4meClient
from pdf4me.optimize import optimize


async def main() -> None:
    api_key = os.environ.get("PDF4ME_API_KEY")
    if not api_key:
        raise SystemExit("Set PDF4ME_API_KEY before running this example.")

    source = Path("input.pdf")
    async with Pdf4meClient(api_key) as client:
        result = await optimize(
            client, source.read_bytes(), doc_name=source.name
        )
    Path("optimized.pdf").write_bytes(result)
    print("Saved optimized.pdf")


if __name__ == "__main__":
    asyncio.run(main())

Run it with:

python optimize_pdf.py

Using actions

Import actions from their module. Pass the client first, document content next, and action options as keyword arguments. Reuse one client for multiple calls; the async context manager closes its connections when finished.

For example, inside an async function with an open client:

from pdf4me.pdf import get_pdf_metadata
from pdf4me.edit import StampAlignX, stamp

metadata = await get_pdf_metadata(client, data, doc_name="input.pdf")
print(metadata.page_count)

stamped = await stamp(client, data, text="DRAFT", align_x=StampAlignX.Center)
Path("stamped.pdf").write_bytes(stamped)

Here, data contains the PDF bytes, for example Path("input.pdf").read_bytes(). Enums such as OptimizeProfile and StampAlignX are exported by the action's module.

Source documents accept bytes, base64 strings, pdf4meblobid://<id> references, or HTTPS URLs. Bytes are encoded automatically. File actions return bytes; JSON actions return typed models, such as DocMetadata or SplitPdfRes. Queued jobs are polled automatically until the result is available.

Every action accepts extra, a dictionary of additional API request fields. Use the API's field names for these values.

Client configuration and errors

async with Pdf4meClient(
    api_key,
    base_url="https://api.pdf4me.com",
    timeout=100,
    max_wait=300,
) as client:
    result = await optimize(client, data)

Durations are in seconds. timeout controls the HTTP request timeout; max_wait limits waiting for a queued job.

OCR actions (convert_ocr_pdf, image_extract_text) wait at least 10 minutes (DEFAULT_OCR_MAX_WAIT), or longer if the client's max_wait is higher. Pass max_wait= to an OCR call to override it for that call.

API failures raise Pdf4meException, importable from pdf4me, with the status code, API message, and trace ID. A queued job exceeding max_wait raises TimeoutError.

Available modules

The client provides 106 actions across 18 modules.

Migrating from 0.8.x

Version 1.0 replaces the whole surface of the library. Upgrading will not be a drop-in change; the four things that break every 0.8.x program are:

• Calls are async. Every action is a coroutine and must be awaited from inside an event loop.
• The client classes are gone. MergeClient, OptimizeClient, SplitClient and the rest are replaced by plain functions, imported from the module for their API section, that take the client as their first argument.
• config.properties is no longer read. Pass the API key to Pdf4meClient yourself. jprops, requests and keyring are no longer dependencies.
• Python 2.7 and 3.6 are no longer supported. The minimum is 3.11.

Files are passed as bytes rather than as the file handles FileReader().get_file_handler(...) used to return, so Path(...).read_bytes() replaces it. Actions that produce a document return bytes; actions that answer with data return a typed model.

The table covers the common calls; the module table above says where to import everything else from, and each action's docstring links its documentation page.

Contributing

Issues and pull requests are welcome on GitHub.

src/pdf4me/_generated/ is generated from the PDF4me OpenAPI description. Edits made there are overwritten the next time the client is regenerated, so please open an issue for anything wrong in that tree - a missing field, a wrong type - rather than patching it. The client and the action modules around it are hand-written and are the right place for a pull request.

The tests run against a fake transport, so they need no API key and make no network calls:

uv run pytest

Releasing

Releases are published to PyPI by the release workflow when a version tag is pushed.

1. Bump the version. uv version sets it in pyproject.toml and updates uv.lock. Commit the change on master:

   uv version 1.0.3
   git commit -am "chore: release 1.0.3"
   git push origin master
   

2. Tag that commit with the same version, prefixed with v, and push the tag:

   git tag v1.0.3
   git push origin v1.0.3
   

The workflow runs the tests on Python 3.11 to 3.14 and checks that the tag matches the pyproject.toml version, stopping before anything ships if they differ. It then builds the distributions, publishes them to PyPI and creates the GitHub release with generated notes. Push only the tag; don't create the GitHub release by hand, because the workflow creates it.

Publishing uses PyPI trusted publishing, so no token is stored in the repository. This repository, release.yml and the pypi environment must be registered as a trusted publisher of the pdf4me project on PyPI.

Support

• Documentation: docs.pdf4me.com
• API keys and account: dev.pdf4me.com
• Bugs and feature requests: GitHub issues
• Email: support-dev@pdf4me.com

Quote the trace_id from a Pdf4meException when reporting an API failure.

Looking for the PDF4me online tools rather than the API? See pdf4me.com.

License

Released under the MIT License.