PDF4me Python SDK Iniziare

IL pdf4me pacchetto su PyPI è l'asincrono ufficiale Python SDK Per il PDF4me REST API. Include 106 funzioni asincrone tipizzate distribuite su 18 moduli che coprono conversione, ottimizzazione, unione, suddivisione, timbratura, firma elettronica, OCRcompilazione moduli, estrazione, codici a barre, ZUGFeRD fatturazione elettronica e AIEstrazione di documenti basata su fatture, ricevute, contratti, estratti conto bancari, documenti fiscali e buste paga.

Informazioni sulla confezione

Campo	Valore
Nome del pacchetto	pdf4me
Versione attuale	1.0.2 (pubblicato il 14/09/2026)
Licenza	MIT
Python supporto	>=3.11 (testato su 3.11, 3.12, 3.13, 3.14)
stato di sviluppo	Produzione/Stabile
Struttura	AsyncIO
Fonte	github.com/pdf4me/pdf4me-clientapi-python
PyPI	pypi.org/project/pdf4me

Dietro le quinte il client viene generato con Microsoft Kiota sopra httpx[http2]Pertanto, ogni azione è completamente tipizzata, restituisce risultati tipizzati e riutilizza un pool di connessioni per client.

Prerequisiti

• Python 3.11 o versioni successive.
• UN PDF4me conto e API chiave.
• pip (O uv, poetry, o qualsiasi PyPI-programma di installazione compatibile).

Ottieni il tuo API Chiave

Visualizza su PyPI

Visualizza su GitHub

Installare

pip

python -m pip install pdf4me

uv

uv add pdf4me

Poetry

poetry add pdf4me

Installazione pdf4me si ferma httpx[http2] e la Microsoft Kiota Pacchetti runtime (microsoft-kiota-abstractions, microsoft-kiota-httpe i backend di serializzazione JSON, form, text e multipart).

Autenticare

Imposta il tuo API chiave nell'ambiente:

Bash / Zsh

export PDF4ME_API_KEY="your-api-key"

PowerShell

$env:PDF4ME_API_KEY = "your-api-key"

Windows CMD

set PDF4ME_API_KEY=your-api-key

Gli esempi seguenti leggono la chiave da quella variabile in fase di esecuzione. Puoi anche passarla direttamente a Pdf4meClient(api_key) se preferisci caricarlo da un gestore segreto, .env file o altra fonte.

Avvio rapido

Il programma più piccolo e utile: apri un client, esegui un'azione, scrivi il risultato su disco.

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())

Tre cose da notare:

1. Un cliente, tante chiamate. IL async with Pdf4meClient(...) il contesto gestisce il sottostante httpx pool di connessioni. Riutilizza lo stesso client per ogni chiamata all'interno main invece di aprirne uno per ogni azione.
2. Le azioni sono funzioni libere, non metodi lato client. Importa ogni azione dal suo modulo (from pdf4me.optimize import optimize, from pdf4me.pdf import get_pdf_metadata) e passa il client come primo argomento. Questo mantiene la superficie piatta e ti permette di eseguire il tree-shaking dei moduli inutilizzati nel tuo editor.
3. Byte in ingresso, byte in uscita. Azioni che producono un ritorno di file bytesLe azioni che producono metadati restituiscono classi di dati tipizzate. Non è previsto alcuno staging su disco, quindi è possibile trasferire i risultati tra le azioni senza intervenire sul file system.

Altre due chiamate comuni

Timbro a PDF:

from pdf4me.edit import StampAlignX, stamp

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

Leggere PDF metadati:

from pdf4me.pdf import get_pdf_metadata

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

Ogni valore passato come enum (come StampAlignX.Center) è una costante tipizzata, quindi il tuo IDE Completa automaticamente i valori validi e mypy o pyright rilevano gli errori di battitura in fase di modifica.

Cosa è disponibile nella confezione (106 azioni suddivise in 18 moduli)

Modulo	Azioni	Esempio di importazione
pdf4me.ai_document_extraction	14	from pdf4me.ai_document_extraction import extract_invoice_data
pdf4me.barcode	7	from pdf4me.barcode import create_barcode, read_barcodes
pdf4me.convert	13	from pdf4me.convert import html_to_pdf, url_to_pdf, word_to_pdf
pdf4me.edit	7	from pdf4me.edit import stamp, add_page_number, add_html_header_footer
pdf4me.excel	1	from pdf4me.excel import excel_to_pdf
pdf4me.extract	8	from pdf4me.extract import extract_text, extract_attachments
pdf4me.find_search	2	from pdf4me.find_search import find_and_replace_text
pdf4me.forms	2	from pdf4me.forms import fill_pdf_form, get_form_fields
pdf4me.generate	6	from pdf4me.generate import generate_document_single
pdf4me.image	13	from pdf4me.image import resize_image, add_watermark_to_image
pdf4me.merge_split	5	from pdf4me.merge_split import merge_pdfs, split_pdf_by_barcode
pdf4me.optimize	1	from pdf4me.optimize import optimize
pdf4me.organize	5	from pdf4me.organize import rotate_pdf, extract_pages
pdf4me.pdf	16	from pdf4me.pdf import get_pdf_metadata, sign_pdf
pdf4me.pdf4me	1	from pdf4me.pdf4me import ping
pdf4me.security	2	from pdf4me.security import protect_document, unlock_pdf
pdf4me.word	2	from pdf4me.word import add_tracked_changes
pdf4me.zugferd	1	from pdf4me.zugferd import create_zugferd_invoice

I percorsi di importazione sopra riportati illustrano la superficie del modulo. Vedi il PDF4me REST API riferimento per l'elenco completo dei parametri per ogni azione e il repository sorgente pdf4me/ Struttura ad albero dei pacchetti per i nomi esatti dei simboli esportati dalla tua versione.

Dove andare dopo?

PDF4me REST API riferimento

Fonte su GitHub

Segnala un problema

Risoluzione dei problemi

ModuleNotFoundError: No module named 'pdf4me'. Il pacchetto è installato in un interprete diverso da quello che esegue lo script. Conferma con python -m pip show pdf4me all'interno dello stesso ambiente virtuale. Se si utilizza pyenv O conda, attivare prima l'ambiente.

SystemExit: Set PDF4ME_API_KEY before running this example. La variabile d'ambiente non è visibile al tuo processo. Riavvia la shell dopo export, oppure passa la chiave direttamente con Pdf4meClient("your-api-key"). Su Windows, ricorda che set all'interno di CMD non persiste tra le sessioni; usa setx per un valore permanente.

httpx.HTTPStatusError: 401 Unauthorized. IL API La chiave è presente ma rifiutata. Rigenerala nel PDF4me pannello di controllo e riprovare.

Prima chiamata lenta dopo un periodo di inattività. HTTP/2 reset keep-alive in stato di inattività. Mantieni il Pdf4meClient rimane aperto per tutta la durata di un processo batch anziché aprirne uno nuovo per ogni file.

asyncio.run() cannot be called from a running event loop. Tu sei dentro Jupyter o un framework che esegue già un ciclo di eventi. Utilizzare await main() al livello superiore di una cella del notebook, oppure racchiudere il codice nel punto di ingresso asincrono del framework stesso.