PDF4me Python SDK Başlarken

O pdf4me paket üzerinde PyPI resmi asenkron Python SDK için PDF4me REST API. Dönüştürme, optimizasyon, birleştirme, bölme, damgalama, elektronik imzalama gibi işlemleri kapsayan 18 modülde 106 adet tipli eşzamansız fonksiyon sunmaktadır. OCRForm doldurma, veri çıkarma, barkodlar, ZUGFeRD e-faturalama ve AIFatura, makbuz, sözleşme, banka ekstresi, vergi belgesi ve maaş bordrolarından veri tabanlı belge çıkarma.

Paket bilgileri

Alan	Değer
Paket adı	pdf4me
Mevcut sürüm	1.0.2 (Yayınlanma tarihi: 14.09.2026)
Lisans	MIT
Python Destek	>=3.11 (3.11, 3.12, 3.13, 3.14 sürümlerinde test edilmiştir)
Gelişim durumu	Üretim/İstikrarlı
Çerçeve	Asenkron
Kaynak	github.com/pdf4me/pdf4me-clientapi-python
PyPI	pypi.org/project/pdf4me

Arka planda istemci Microsoft tarafından oluşturulmaktadır. Kiota üstüne httpx[http2]Bu sayede her işlem tamamen tiplendirilmiş olur, tiplendirilmiş sonuçlar döndürür ve her istemci için tek bir bağlantı havuzu yeniden kullanılır.

Önkoşullar

• Python 3.11 veya daha yeni sürüm.
• A PDF4me hesap ve API anahtar.
• pip (veya uv, poetryveya herhangi bir PyPI-uyumlu yükleyici).

Alın API Anahtar

Görüntüle PyPI

Görüntüle GitHub

Düzenlemek

pip

python -m pip install pdf4me

uv

uv add pdf4me

Poetry

poetry add pdf4me

Kurulum pdf4me içeri çekiyor httpx[http2] ve Microsoft Kiota çalışma zamanı paketleri (microsoft-kiota-abstractions, microsoft-kiota-http(ve JSON, form, metin ve çok parçalı serileştirme arka uçları).

Kimlik doğrulama

Ayarlarınızı yapın. API Çevredeki anahtar:

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

Aşağıdaki örnekler, çalışma zamanında bu değişkenden anahtarı okur. Ayrıca doğrudan da iletebilirsiniz. Pdf4meClient(api_key) Eğer dosyayı bir gizli kod yöneticisinden yüklemeyi tercih ederseniz, .env dosya veya başka bir kaynak.

Hızlı başlangıç

En basit kullanışlı program: bir istemci açın, bir işlem çalıştırın, sonucu diske yazın.

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

Dikkat edilmesi gereken üç şey:

1. Tek bir müşteri, birçok telefon görüşmesi. O async with Pdf4meClient(...) bağlam, temel unsurları yönetir. httpx Bağlantı havuzu. İçerideki her çağrı için aynı istemciyi yeniden kullanın. main Her işlem için ayrı bir tane açmak yerine.
2. Eylemler, istemci yöntemleri değil, serbest işlevlerdir. Her bir eylemi ilgili modülden içe aktarın (from pdf4me.optimize import optimize, from pdf4me.pdf import get_pdf_metadata) ve istemciyi ilk argüman olarak iletin. Bu, yüzeyi düz tutar ve editörünüzde kullanılmayan modülleri ağaç budama yöntemiyle temizlemenizi sağlar.
3. Giren baytlar, çıkan baytlar. Dosya döndüren eylemler bytesMeta veri üreten işlemler, tür belirtilmiş veri sınıfları döndürür. Disk üzerinde geçici depolama olmadığı için, dosya sistemine dokunmadan işlemler arasında sonuçları aktarabilirsiniz.

İki yaygın çağrı daha

Damgala PDF:

from pdf4me.edit import StampAlignX, stamp

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

Okumak PDF meta veriler:

from pdf4me.pdf import get_pdf_metadata

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

Enum olarak geçirilen her değer (örneğin StampAlignX.Center) türü belirtilmiş bir sabittir, bu nedenle sizin IDE Yasal değerleri otomatik olarak tamamlar ve mypy veya pyright düzenleme sırasında yazım hatalarını yakalar.

Kutunun içeriği (18 modülde toplam 106 işlem)

Modül	Eylemler	İçe aktarma örneği
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

Yukarıdaki içe aktarma yolları, modül yüzeyini göstermektedir. Bkz. PDF4me REST API referans Her eylem için eksiksiz parametre listesi ve kaynak deposunun bilgileri için pdf4me/ Sürümünüzün dışa aktardığı tam sembol adları için paket ağacı.

Bundan sonra nereye gideceğiz?

PDF4me REST API referans

Kaynak GitHub

Bir sorun bildirin

Sorun giderme

ModuleNotFoundError: No module named 'pdf4me'. Paket, komut dosyanızı çalıştıran yorumlayıcıdan farklı bir yorumlayıcıda yüklenmiştir. Bunu aşağıdaki komutla doğrulayın. python -m pip show pdf4me Aynı sanal ortam içinde. Eğer kullanıyorsanız pyenv veya condaÖncelikle ortamı etkinleştirin.

SystemExit: Set PDF4ME_API_KEY before running this example. Ortam değişkeni işleminiz tarafından görülemiyor. Kabuğunuzu yeniden başlatın. exportveya anahtarı doğrudan iletin Pdf4meClient("your-api-key")Windows'ta şunu unutmayın: set CMD içindeki ayarlar oturumlar arasında kalıcı olmaz; kullanın setx kalıcı bir değer için.

httpx.HTTPStatusError: 401 Unauthorized. O API Anahtar mevcut ancak reddedildi. Yeniden oluşturun. PDF4me gösterge paneli ve tekrar deneyin.

Bir süre işlem yapılmamasının ardından gelen ilk arama yavaş gerçekleşti. HTTP/2 keep-alive, boşta kaldığında sıfırlanır. Pdf4meClient Dosya başına yeni bir dosya açmak yerine, toplu işlem süresince açık kalacak şekilde yapılandırın.

asyncio.run() cannot be called from a running event loop. İçeridesiniz Jupyter veya halihazırda bir olay döngüsü çalıştıran bir çerçeve kullanın. await main() Not defteri hücresinin en üst düzeyinde kodunuzu yazdırabilir veya çerçevenin kendi eşzamansız giriş noktasına sarabilirsiniz.