Skip to content
PDF Oxide

Python-API-Referenz

PDF Oxide stellt native Python-Bindings bereit, die mit PyO3 erstellt wurden. Fertige Wheels gibt es für Python 3.8–3.14 auf Linux, macOS und Windows (x86_64 und ARM64).

pip install pdf_oxide

Die Rust-API finden Sie in der Rust-API-Referenz. Die JavaScript-API finden Sie in der Node.js-API-Referenz oder der WASM-API-Referenz. Details zu Typen finden Sie unter Typen & Enums.

PdfDocument

Die zentrale Klasse zum Öffnen, Extrahieren, Bearbeiten und Speichern von PDF-Dateien.

from pdf_oxide import PdfDocument

Konstruktor

PdfDocument(path: str, password: str | None = None)
Parameter Typ Beschreibung
path str Pfad zur PDF-Datei
password str | None Optionales Passwort für verschlüsselte PDFs (Standard: None)

Übergeben Sie password=, um verschlüsselte PDFs in einem Schritt zu öffnen. Alternativ können Sie nach dem Öffnen doc.authenticate(password) aufrufen.

Löst FileNotFoundError aus, wenn die Datei nicht existiert. Löst PdfError aus, wenn die Datei keine gültige PDF ist.

Klassenmethoden

PdfDocument.from_bytes(data: bytes, password: str | None = None) -> PdfDocument

Öffnet eine PDF aus In-Memory-Bytes (z. B. aus S3 heruntergeladen, per HTTP empfangen). Akzeptiert ein optionales Passwort für verschlüsselte PDFs.

Parameter Typ Beschreibung
data bytes Rohe Bytes der PDF-Datei
password str | None Optionales Passwort für verschlüsselte PDFs (Standard: None) 
from pdf_oxide import PdfDocument

# Open PDF from bytes (e.g., downloaded from S3)
doc = PdfDocument.from_bytes(pdf_bytes)

# Also supports password:
doc = PdfDocument.from_bytes(pdf_bytes, password="secret")

Methoden

Allgemein

Methode Rückgabetyp Beschreibung
version() tuple[int, int] PDF-Version als (major, minor) (z. B. (1, 7))
authenticate(password) bool Verschlüsselte PDF mit Benutzer- oder Eigentümerpasswort authentifizieren

Dokumentinfo

doc.page_count() -> int

Gibt die Anzahl der Seiten im Dokument zurück.

doc.has_structure_tree() -> bool

Prüft, ob das Dokument ein Tagged PDF mit Strukturbaum ist.

Authentifizierung

doc.authenticate(password: str) -> bool

Authentifizierung mit einem Passwort nach dem Öffnen. Gibt True zurück, wenn die Authentifizierung erfolgreich war.

Textextraktion

doc.extract_text(
    page: int,
    region: tuple[float, float, float, float] | None = None,
    exclude_layers: list[str] | None = None,
    exclude_inks: list[str] | None = None,
    extract_tables: bool = True
) -> str

Extrahiert Klartext aus einer einzelnen Seite. Seiten sind nullbasiert indexiert. Optional auf eine region zuschneiden, benannte Optional-Content-Ebenen oder Ink-/Separations-Namen ausschließen und die Tabellenrekonstruktion ein- bzw. ausschalten.

doc.extract_chars(
    page: int,
    region: tuple[float, float, float, float] | None = None,
    exclude_layers: list[str] | None = None,
    exclude_inks: list[str] | None = None
) -> list[TextChar]

Extrahiert Position und Font-Metadaten pro Zeichen. Gibt eine Liste von TextChar-Objekten zurück.

doc.extract_spans(page: int, region: tuple | None = None, reading_order: str | None = None) -> list[TextSpan]

Extrahiert Text-Spans mit Font-Metadaten. Jeder Span ist ein zusammenhängender Lauf gleich formatierten Texts. Übergeben Sie reading_order="column_aware" für mehrspaltige PDFs.

doc.extract_words(
    page: int,
    *,
    include_artifacts: bool = True,
    region: tuple | None = None,
    word_gap_threshold: float | None = None,
    profile: ExtractionProfile | None = None
) -> list[TextWord]

Extrahiert wortgruppierten Text mit Begrenzungsrahmen. Gibt eine Liste von TextWord-Objekten zurück.

doc.extract_text_lines(
    page: int,
    *,
    include_artifacts: bool = True,
    region: tuple | None = None,
    word_gap_threshold: float | None = None,
    line_gap_threshold: float | None = None,
    profile: ExtractionProfile | None = None
) -> list[TextLine]

Extrahiert zeilengruppierten Text. Gibt eine Liste von TextLine-Objekten zurück.

doc.extract_page_text(page: int, reading_order: str | None = None) -> dict

Extrahiert Spans, Zeichen und Seitenmaße in einem einzigen Durchlauf. Gibt ein Dict mit den Schlüsseln spans, chars, page_width, page_height und text zurück. Effizienter, als extract_spans() und extract_chars() getrennt aufzurufen.

doc.page_layout_params(page: int) -> LayoutParams

Berechnet adaptive Layout-Parameter (Wort-/Zeilenabstands-Schwellen, Medianmetriken, Spaltenanzahl) für eine Seite. Siehe LayoutParams.

doc.within(page: int, bbox: tuple[float, float, float, float]) -> PdfPageRegion

Erzeugt ein zugeschnittenes Region-Handle, um Text, Wörter, Zeilen, Tabellen, Bilder und Pfade innerhalb von bbox zu extrahieren. Siehe PdfPageRegion.

Auto-Extraktion & Klassifizierung

doc.extract_text_auto(page: int) -> str

Wählt automatisch die beste Extraktionsstrategie (nativer Text vs. OCR) für eine Seite und gibt Klartext zurück.

doc.extract_page_auto(page: int, options_json: str | None = None) -> str

Extrahiert eine Seite automatisch und gibt ein JSON-Dokument zurück; übergeben Sie einen JSON-String options_json, um die Pipeline anzupassen.

doc.classify_page(page: int) -> str

Klassifiziert eine einzelne Seite (z. B. "text", "scanned", "mixed").

doc.classify_document() -> str

Klassifiziert das gesamte Dokument anhand einer Stichprobe seiner Seiten.

doc.has_text_layer(page: int) -> bool

Prüft, ob eine Seite bereits eine extrahierbare native Textebene besitzt (anstatt OCR zu erfordern).

Konvertierung

doc.to_plain_text(
    page: int,
    preserve_layout: bool = False,
    detect_headings: bool = True,
    include_images: bool = True,
    image_output_dir: str | None = None
) -> str

Konvertiert eine Seite in Klartext mit Layout-Optionen.

doc.to_plain_text_all(
    preserve_layout: bool = False,
    detect_headings: bool = True,
    include_images: bool = True,
    image_output_dir: str | None = None
) -> str

Konvertiert alle Seiten in Klartext.

doc.to_markdown(
    page: int,
    preserve_layout: bool = False,
    detect_headings: bool = True,
    include_images: bool = True,
    image_output_dir: str | None = None,
    embed_images: bool = True,
    include_form_fields: bool = True
) -> str

Konvertiert eine Seite in Markdown.

doc.to_markdown_all(
    preserve_layout: bool = False,
    detect_headings: bool = True,
    include_images: bool = True,
    image_output_dir: str | None = None,
    embed_images: bool = True,
    include_form_fields: bool = True
) -> str

Konvertiert alle Seiten in Markdown.

doc.to_html(
    page: int,
    preserve_layout: bool = False,
    detect_headings: bool = True,
    include_images: bool = True,
    image_output_dir: str | None = None,
    embed_images: bool = True,
    include_form_fields: bool = True
) -> str

Konvertiert eine Seite in HTML.

doc.to_html_all(
    preserve_layout: bool = False,
    detect_headings: bool = True,
    include_images: bool = True,
    image_output_dir: str | None = None,
    embed_images: bool = True,
    include_form_fields: bool = True
) -> str

Konvertiert alle Seiten in HTML.

Office-Konvertierung

Methode Rückgabetyp Beschreibung
to_docx(path) – Konvertiert die PDF in eine Word-Dokumentdatei
to_docx_bytes() bytes Konvertiert die PDF in DOCX-Bytes
to_pptx(path) – Konvertiert die PDF in eine PowerPoint-Datei
to_pptx_bytes() bytes Konvertiert die PDF in PPTX-Bytes
to_xlsx(path) – Konvertiert die PDF in eine Excel-Arbeitsmappendatei
to_xlsx_bytes() bytes Konvertiert die PDF in XLSX-Bytes

Bildextraktion

doc.extract_images(page: int) -> list[ImageInfo]

Extrahiert alle Bilder einer Seite, einschließlich Bildern in Content Streams und verschachtelten Form-XObjects.

doc.extract_image_bytes(page: int) -> list[dict]

Extrahiert rohe Bild-Bytes aus einer Seite. Jedes Dict enthält width, height, data (Bytes) und format.

Suche

doc.search(
    pattern: str,
    case_insensitive: bool = False,
    literal: bool = False,
    whole_word: bool = False,
    max_results: int = 0
) -> list[SearchResult]

Sucht Text über alle Seiten hinweg. Setzen Sie max_results=0 für unbegrenzte Ergebnisse. Gibt eine Liste von Treffern mit Seitennummer, Text und Koordinaten zurück.

doc.search_page(
    page: int,
    pattern: str,
    case_insensitive: bool = False,
    literal: bool = False,
    whole_word: bool = False,
    max_results: int = 0
) -> list[SearchResult]

Sucht Text auf einer einzelnen Seite.

Metadaten bearbeiten

Methode Parameter Beschreibung
set_title(title) str Dokumenttitel setzen
set_author(author) str Dokumentautor setzen
set_subject(subject) str Dokumentbetreff setzen
set_keywords(keywords) str Dokumentschlüsselwörter setzen

Seitendrehung

Methode Parameter Rückgabe Beschreibung
page_rotation(page) int int Aktuelle Drehung abrufen (0, 90, 180, 270)
set_page_rotation(page, degrees) int, int – Absolute Drehung setzen
rotate_page(page, degrees) int, int – Zur aktuellen Drehung addieren
rotate_all_pages(degrees) int – Alle Seiten drehen

Seitenmaße

Methode Parameter Rückgabe Beschreibung
page_media_box(page) int tuple[float, float, float, float] MediaBox abrufen (llx, lly, urx, ury)
set_page_media_box(page, llx, lly, urx, ury) int, float, float, float, float – MediaBox setzen
page_crop_box(page) int `tuple None`
set_page_crop_box(page, llx, lly, urx, ury) int, float, float, float, float – CropBox setzen
crop_margins(left, right, top, bottom) float, float, float, float – Alle Seitenränder beschneiden

Löschen / Übermalen

Methode Parameter Beschreibung
erase_region(page, llx, lly, urx, ury) int, float, float, float, float Eine rechteckige Region löschen
erase_regions(page, rects) int, list[tuple] Mehrere Regionen löschen
clear_erase_regions(page) int Ausstehende Löschvorgänge verwerfen

Anmerkungen

doc.get_annotations(page: int) -> list[dict]

Ruft Anmerkungs-Metadaten (Typ, Rechteck, Inhalt usw.) für eine Seite ab.

Methode Parameter Rückgabe Beschreibung
flatten_page_annotations(page) int – Anmerkungen einer Seite flachzeichnen
flatten_all_annotations() – – Alle Anmerkungen flachzeichnen
is_page_marked_for_flatten(page) int bool Prüfen, ob die Seite zum Flachzeichnen markiert ist
unmark_page_for_flatten(page) int – Markierung zum Flachzeichnen einer Seite aufheben

Schwärzung

doc.add_redaction(
    page: int,
    rect: tuple[float, float, float, float],
    fill: tuple[float, float, float] | None = None
) -> None

Markiert eine rechteckige Region zur Schwärzung mit einer optionalen RGB-Füllfarbe.

doc.redaction_count(page: int) -> int

Gibt die Anzahl der ausstehenden Schwärzungen auf einer Seite zurück.

doc.apply_redactions_destructive(
    scrub_metadata: bool = True,
    remove_javascript: bool = True,
    remove_embedded_files: bool = True,
    fill: tuple[float, float, float] = (0.0, 0.0, 0.0)
) -> None

Wendet alle Schwärzungen destruktiv an, entfernt den darunterliegenden Inhalt und bereinigt optional Metadaten, JavaScript und eingebettete Dateien.

doc.sanitize_document(
    scrub_metadata: bool = True,
    remove_javascript: bool = True,
    remove_embedded_files: bool = True
) -> None

Bereinigt das Dokument, ohne Regionen zu schwärzen: entfernt Metadaten, JavaScript und/oder eingebettete Dateien.

Methode Parameter Rückgabe Beschreibung
apply_page_redactions(page) int – Schwärzungen auf einer Seite anwenden
apply_all_redactions() – – Alle ausstehenden Schwärzungen anwenden
is_page_marked_for_redaction(page) int bool Prüfen, ob die Seite zur Schwärzung markiert ist
unmark_page_for_redaction(page) int – Markierung zur Schwärzung einer Seite aufheben

Ebenen & Inks

Methode Parameter Rückgabe Beschreibung
get_layers() – list[str] Namen der Optional-Content-Ebenen (OCG) auflisten
get_page_inks(page) int list[str] Ink-/Separations-Farbnamen auf einer Seite auflisten
get_page_inks_deep(page) int list[str] Inks einschließlich der in Form-XObjects verschachtelten auflisten

Kopf-/Fußzeilen-Bereinigung

doc.remove_headers(threshold: float = 0.8) -> int
doc.remove_footers(threshold: float = 0.8) -> int
doc.remove_artifacts(threshold: float = 0.8) -> int

Erkennt und entfernt wiederkehrende Kopfzeilen, Fußzeilen oder Seitenartefakte im gesamten Dokument. threshold ist das seitenübergreifende Wiederholungsverhältnis. Gibt die Anzahl der entfernten Elemente zurück.

Methode Parameter Beschreibung
erase_header(page) int Die erkannte Kopfzeilenregion auf einer Seite löschen
edit_header(page) int Die Kopfzeilenregion zur Bearbeitung markieren
erase_footer(page) int Die erkannte Fußzeilenregion auf einer Seite löschen
edit_footer(page) int Die Fußzeilenregion zur Bearbeitung markieren
erase_artifacts(page) int Erkannte Artefakte auf einer Seite löschen
sync_editor_erasures() – Ausstehende Kopf-/Fußzeilen-/Artefakt-Löschungen in den Editor übernehmen

Formularfelder

doc.get_form_fields() -> list[FormField]

Ruft alle Formularfelder ab. Eigenschaften siehe FormField.

doc.get_form_field_value(name: str) -> str | bool | list | None

Ruft einen Formularfeldwert anhand des Namens ab. Gibt den passenden Python-Typ je nach Feldtyp zurück.

doc.set_form_field_value(name: str, value: str | bool) -> None

Setzt einen Formularfeldwert anhand des Namens.

doc.has_xfa() -> bool

Prüft, ob das Dokument XFA-Formulare enthält.

doc.export_form_data(path: str, format: str = "fdf") -> None

Exportiert Formulardaten in eine Datei. Unterstützte Formate: "fdf" und "xfdf".

Methode Parameter Beschreibung
flatten_forms() – Alle Formularfelder in den Seiteninhalt flachzeichnen
flatten_forms_on_page(page) int Formulare auf einer bestimmten Seite flachzeichnen

Bildmanipulation

doc.page_images(page: int) -> list[dict]

Ruft Bildnamen und -grenzen für Positionierungsoperationen ab. Jedes Dict enthält name, bounds [x, y, width, height] und matrix.

Methode Parameter Beschreibung
reposition_image(page, name, x, y) int, str, float, float Ein Bild verschieben
resize_image(page, name, width, height) int, str, float, float Größe eines Bilds ändern
set_image_bounds(page, name, x, y, width, height) int, str, float, float, float, float Position und Größe eines Bilds setzen
clear_image_modifications(page) int Ausstehende Bildänderungen verwerfen
has_image_modifications(page) int → bool Auf ausstehende Bildänderungen prüfen

Dokumentoperationen

doc.merge_from(source: str | PdfDocument) -> int

Führt Seiten aus einer anderen PDF zusammen. Akzeptiert einen Dateipfad oder eine PdfDocument-Instanz. Gibt die Anzahl der zusammengeführten Seiten zurück.

doc.embed_file(name: str, data: bytes) -> None

Hängt eine Datei an die PDF an.

doc.get_outline() -> list[dict] | None

Ruft Lesezeichen / Inhaltsverzeichnis des Dokuments ab. Gibt None zurück, wenn keine Gliederung existiert.

doc.extract_paths(page: int, region: tuple | None = None) -> list[dict]

Ruft Vektorpfade (Linien, Kurven, Formen) einer Seite ab.

doc.extract_rects(page: int, region: tuple | None = None) -> list[dict]

Ruft achsenparallele Rechtecke (aus gefüllten/umrandeten Pfaden) auf einer Seite ab.

doc.extract_lines(page: int, region: tuple | None = None) -> list[dict]

Ruft gerade Liniensegmente auf einer Seite ab.

doc.extract_tables(page: int, region: tuple | None = None, table_settings: dict | None = None) -> list[dict]

Erkennt und extrahiert Tabellen. Jede Tabelle ist ein Dict mit Zeilen und Zellen (Text + Begrenzungsrahmen). Übergeben Sie table_settings, um die Erkennungsstrategie anzupassen.

doc.extract_structured(page: int) -> str

Extrahiert die Seite als strukturiertes JSON-Dokument (logische Lesereihenfolge, Blöcke und Rollen).

doc.page_labels() -> list[dict]

Ruft Seitenlabel-Bereiche ab. Jedes Dict enthält start_page, style, prefix und start_value.

doc.xmp_metadata() -> dict | None

Ruft XMP-Metadaten als Dictionary mit Feldern wie dc_title, dc_creator, xmp_create_date usw. ab. Gibt None zurück, wenn keine XMP-Metadaten existieren.

OCR

doc.extract_text_ocr(page: int, engine: OcrEngine | None = None) -> str

Extrahiert Text per OCR. Erfordert das ocr-Feature im Rust-Build. Übergeben Sie eine eigene OcrEngine oder None für die Standard-Engine.

Seitenextraktion & Neuanordnung

doc.extract_pages(pages: list[int], output: str) -> None

Extrahiert die angegebenen Seitenindizes in eine neue PDF-Datei unter output.

doc.extract_pages_to_bytes(pages: list[int]) -> bytes

Extrahiert die angegebenen Seitenindizes in eine neue PDF, die als Bytes zurückgegeben wird.

doc.extract_page_ranges_to_bytes(ranges: list[tuple[int, int]]) -> bytes

Extrahiert einen oder mehrere (start, end)-Seitenbereiche in eine neue PDF, die als Bytes zurückgegeben wird.

Methode Parameter Beschreibung
select_pages(pages) list[int] Nur die aufgeführten Seiten in der angegebenen Reihenfolge behalten
delete_page(index) int Eine einzelne Seite löschen
move_page(from_index, to_index) int, int Eine Seite an eine neue Position verschieben

Konformität & Validierung

doc.validate_pdf_a(level: str = "1b") -> dict

Validiert gegen eine PDF/A-Konformitätsstufe (z. B. "1b", "2b", "3b"). Gibt ein Report-Dict zurück.

doc.convert_to_pdf_a(level: str = "2b") -> dict

Konvertiert das Dokument in PDF/A und gibt ein Konvertierungs-Report-Dict zurück.

doc.validate_pdf_ua() -> dict

Validiert gegen die PDF/UA-Anforderungen (Barrierefreiheit).

doc.validate_pdf_x(level: str = "1a_2001") -> dict

Validiert gegen eine PDF/X-Konformitätsstufe (Druckproduktion).

Berechtigungen & Warnungen

doc.permissions() -> dict

Gibt die Verschlüsselungs-Berechtigungsflags des Dokuments zurück (Drucken, Kopieren, Ändern, Anmerken usw.).

doc.structured_warnings() -> list

Gibt Warnungen zurück, die während der strukturierten / getaggten Inhaltsextraktion gesammelt wurden.

doc.flatten_warnings() -> list[str]

Gibt Warnungen zurück, die während des Flachzeichnens von Formularen/Anmerkungen gesammelt wurden.

Signaturen & Document Security Store

doc.signatures() -> list[Signature]

Gibt alle digitalen Signaturen im Dokument zurück. Siehe Signature.

doc.signature_count() -> int

Gibt die Anzahl der digitalen Signaturen zurück.

doc.dss() -> Dss | None

Gibt den geparsten Document Security Store (LTV-Material) des Dokuments zurück oder None. Siehe Dss.

Page-API (v0.3.34)

PdfDocument ist iterierbar und indexierbar und liefert lazy Page-Objekte. Siehe Page.

len(doc)                  # number of pages
doc[i]                    # page at index i (negative indexing supported)
doc[-1]                   # last page
for page in doc: ...      # iterate pages

DOM-Zugriff

doc.page(index: int) -> PdfPage

Ruft ein DOM-ähnliches Seiten-Handle für die Bearbeitung auf Elementebene ab. Siehe PdfPage.

doc.save_page(page: PdfPage) -> None

Speichert eine geänderte PdfPage zurück in das Dokument.

Rendering

doc.render_page(
    page: int,
    dpi: int | None = None,
    format: str | None = None,
    background: tuple[float, float, float, float] | None = None,
    transparent: bool = False,
    render_annotations: bool | None = None,
    jpeg_quality: int | None = None,
    excluded_layers: list[str] | None = None
) -> bytes

Rendert eine Seite in PNG- oder JPEG-Bytes mit Kontrolle über DPI, Hintergrund, Transparenz, Anmerkungs-Rendering, JPEG-Qualität und ausgeschlossene Ebenen.

doc.render_pixmap(page: int, dpi: int | None = None) -> RenderedPixmap

Rendert eine Seite in ein rohes RGBA-RenderedPixmap (Named Tuple mit width, height, data).

doc.render_separations(page: int, dpi: int | None = None) -> list[SeparationPlate]

Rendert Separations-Druckplatten pro Ink für eine Seite. Gibt eine Liste von SeparationPlate-Named-Tuples (name, width, height, data) zurück.

doc.render_separation(page: int, ink_name: str, dpi: int | None = None) -> SeparationPlate

Rendert eine einzelne benannte Ink-Separationsplatte.

Methode Rückgabetyp Beschreibung
render_page_fit(page, fit_width, fit_height, format=0) bytes Eine Seite skaliert in eine Pixelbox einpassen
flatten_to_images(dpi=150) bytes Alle Seiten in eine bildbasierte PDF flachzeichnen

Speichern

doc.save(path: str, compress: bool = True, garbage_collect: bool = True, linearize: bool = False) -> None

Speichert die PDF in eine Datei. Schaltet Stream-Komprimierung, Garbage Collection toter Objekte und Linearisierung (Fast Web View) um.

doc.to_bytes(compress: bool = True, garbage_collect: bool = True, linearize: bool = False) -> bytes

Serialisiert die PDF zu Bytes mit denselben Optionen wie save().

doc.save_encrypted(
    path: str,
    user_password: str,
    owner_password: str | None = None,
    allow_print: bool = True,
    allow_copy: bool = True,
    allow_modify: bool = True,
    allow_annotate: bool = True
) -> None

Speichert mit AES-256-Passwortschutz und Berechtigungssteuerung. Wenn owner_password None ist, wird das Benutzerpasswort verwendet.

doc.to_bytes_encrypted(
    user_password: str,
    owner_password: str | None = None,
    allow_print: bool = True,
    allow_copy: bool = True,
    allow_modify: bool = True,
    allow_annotate: bool = True
) -> bytes

Serialisiert eine AES-256-verschlüsselte PDF zu Bytes.

Page

Ein lazy Seiten-Handle, das von doc[i] oder beim Iterieren über PdfDocument zurückgegeben wird. Alle Properties werden beim Zugriff berechnet und an das übergeordnete Dokument delegiert.

from pdf_oxide import PdfDocument

with PdfDocument("paper.pdf") as doc:
    page = doc[0]
    text = page.text
    md = page.markdown(detect_headings=True)

Properties (lazy)

Property Typ Beschreibung
index int Nullbasierter Seitenindex
width, height float Seitenmaße in PDF-Punkten
bbox tuple[float, 4] (llx, lly, urx, ury)
text str Extrahierter Klartext
chars, words, lines, spans list[...] Strukturierter Text
tables list[dict] Tabellen mit Zeilen + Zellen (Text + bboxes)
images, paths, annotations list[...] Seiteninhalt

Methoden

page.markdown(preserve_layout=False, detect_headings=True,
              include_images=False, image_output_dir=None,
              embed_images=True, include_form_fields=True) -> str
page.plain_text(...) -> str
page.html(...) -> str
page.render(dpi=None, format=None, background=None, transparent=False,
            render_annotations=None, jpeg_quality=None, excluded_layers=None) -> bytes
page.render_pixmap(dpi=None) -> RenderedPixmap
page.search(pattern, case_insensitive=False, literal=False,
            whole_word=False, max_results=100) -> list
page.region(x, y, width, height) -> PdfPageRegion

Das lazy Seitenobjekt ist auch als doc.pages() verfügbar (ein Iterator, der dem direkten Iterieren über das Dokument entspricht).

PdfPage

DOM-ähnliches Seiten-Handle für den Zugriff und die Bearbeitung auf Elementebene. Wird über PdfDocument.page() abgerufen.

from pdf_oxide import PdfDocument

doc = PdfDocument("file.pdf")
page = doc.page(0)

Properties

Property Typ Beschreibung
index int Nullbasierter Seitenindex
width float Seitenbreite in PDF-Punkten
height float Seitenhöhe in PDF-Punkten

Methoden

page.children() -> list[PdfElement]

Ruft alle Elemente der Seite ab.

page.find_text_containing(needle: str) -> list[PdfText]

Findet alle Textelemente, die den angegebenen Teilstring enthalten.

page.find_images() -> list[PdfImage]

Findet alle Bildelemente der Seite.

page.get_element(element_id: str) -> PdfElement | None

Ruft ein bestimmtes Element anhand seiner ID ab.

page.set_text(text_id: PdfTextId, new_text: str) -> None

Ersetzt den Textinhalt eines durch seine PdfTextId identifizierten Elements.

page.annotations() -> list[PdfAnnotation]

Ruft alle Anmerkungen der Seite ab.

page.add_link(x: float, y: float, width: float, height: float, url: str) -> str

Fügt eine URL-Link-Anmerkung hinzu. Gibt die Anmerkungs-ID zurück.

page.add_highlight(x: float, y: float, width: float, height: float, color: tuple[float, float, float]) -> str

Fügt eine Hervorhebungs-Anmerkung mit RGB-Farbe hinzu. Gibt die Anmerkungs-ID zurück.

page.add_note(x: float, y: float, text: str) -> str

Fügt eine Haftnotiz-Anmerkung hinzu. Gibt die Anmerkungs-ID zurück.

page.remove_annotation(index: int) -> bool

Entfernt eine Anmerkung anhand des Index. Gibt True zurück, wenn sie entfernt wurde.

page.add_text(text: str, x: float, y: float, font_size: float = 12.0) -> PdfTextId

Fügt neuen Text zur Seite hinzu. Gibt eine PdfTextId zur späteren Referenzierung zurück.

page.remove_element(element_id: PdfTextId) -> bool

Entfernt ein Element anhand seiner ID. Gibt True zurück, wenn es entfernt wurde.

Beispiel

from pdf_oxide import PdfDocument

doc = PdfDocument("invoice.pdf")
page = doc.page(0)

# Find and replace text
for text in page.find_text_containing("DRAFT"):
    page.set_text(text.id, "FINAL")

# Add a link
page.add_link(100, 700, 200, 20, "https://example.com")

doc.save_page(page)
doc.save("invoice_updated.pdf")

Pdf

Die einheitliche Klasse zum Erstellen von PDFs aus verschiedenen Quellformaten.

from pdf_oxide import Pdf

Factory-Methoden

Pdf.from_markdown(content: str, title: str | None = None, author: str | None = None) -> Pdf

Erstellt eine PDF aus Markdown-Inhalt.

Pdf.from_html(content: str, title: str | None = None, author: str | None = None) -> Pdf

Erstellt eine PDF aus HTML-Inhalt.

Pdf.from_text(content: str, title: str | None = None, author: str | None = None) -> Pdf

Erstellt eine PDF aus Klartext.

Pdf.from_markdown_with_template(content: str, template: str, title: str | None = None, author: str | None = None) -> Pdf

Erstellt eine PDF aus Markdown, gerendert über eine benannte CSS-/Layout-Vorlage.

Pdf.from_image(path: str) -> Pdf

Erstellt eine einseitige PDF aus einer Bilddatei (JPEG, PNG).

Pdf.from_bytes(data: bytes) -> Pdf

Öffnet eine bestehende PDF aus In-Memory-Bytes zur Bearbeitung. Praktisch zum Laden von PDFs, die aus S3, HTTP oder Datenbanken heruntergeladen wurden.

from pdf_oxide import Pdf

pdf = Pdf.from_bytes(existing_pdf_bytes)
pdf.save("modified.pdf")

Pdf.from_images(paths: list[str]) -> Pdf

Erstellt eine mehrseitige PDF aus mehreren Bilddateien, eine Seite pro Bild.

Pdf.from_image_bytes(data: bytes) -> Pdf

Erstellt eine einseitige PDF aus Bild-Bytes.

Pdf.merge(paths: list[str]) -> Pdf

Führt mehrere PDF-Dateien (über Pfade) zu einer einzigen Pdf zusammen.

Methoden

pdf.save(path: str) -> None

Speichert die PDF in eine Datei.

pdf.to_bytes() -> bytes

Ruft den PDF-Inhalt als Bytes ab.

len(pdf) -> int

Ruft die PDF-Größe in Bytes ab (über __len__).

PdfText

Repräsentiert ein Textelement auf einer Seite. Wird von PdfPage.find_text_containing() zurückgegeben.

Property Typ Beschreibung
id PdfTextId Eindeutige Element-Kennung
value str Textinhalt
text str Textinhalt (Alias für value)
bbox tuple[float, float, float, float] Begrenzungsrahmen (x0, y0, x1, y1)
font_name str PostScript-Schriftname
font_size float Schriftgröße in Punkt
is_bold bool Ob der Text fett ist
is_italic bool Ob der Text kursiv ist

Methoden

Methode Parameter Rückgabe Beschreibung
contains(needle) str bool Prüfen, ob der Text einen Teilstring enthält
starts_with(prefix) str bool Prüfen, ob der Text mit einem Präfix beginnt
ends_with(suffix) str bool Prüfen, ob der Text mit einem Suffix endet

PdfImage

Repräsentiert ein Bildelement auf einer Seite. Wird von PdfPage.find_images() zurückgegeben.

Property Typ Beschreibung
bbox tuple[float, float, float, float] Begrenzungsrahmen (x0, y0, x1, y1)
width int Bildbreite in Pixeln
height int Bildhöhe in Pixeln
aspect_ratio float Verhältnis Breite / Höhe

PdfAnnotation

Repräsentiert eine Anmerkung auf einer Seite. Wird von PdfPage.annotations() zurückgegeben.

Property Typ Beschreibung
subtype str Anmerkungstyp (z. B. "Link", "Highlight", "Text")
rect tuple[float, float, float, float] Position (x0, y0, x1, y1)
contents `str None`
color `tuple[float, float, float] None`
is_modified bool Ob die Anmerkung geändert wurde
is_new bool Ob die Anmerkung neu hinzugefügt wurde

PdfElement

Generischer Element-Wrapper. Wird von PdfPage.children() zurückgegeben.

Methode Rückgabe Beschreibung
is_text() bool Prüfen, ob das Element Text ist
is_image() bool Prüfen, ob das Element ein Bild ist
is_path() bool Prüfen, ob das Element ein Vektorpfad ist
is_table() bool Prüfen, ob das Element eine Tabelle ist
is_structure() bool Prüfen, ob das Element ein Strukturelement ist
as_text() `PdfText None`
as_image() `PdfImage None`
Property Typ Beschreibung
bbox tuple[float, float, float, float] Begrenzungsrahmen

TextChar

Repräsentiert ein einzelnes Zeichen mit Position und Font-Metadaten. Wird von PdfDocument.extract_chars() zurückgegeben.

from pdf_oxide import TextChar  # or access via PdfDocument
Attribut Typ Beschreibung
char str Das Unicode-Zeichen
bbox tuple[float, float, float, float] Begrenzungsrahmen (x0, y0, x1, y1)
font_name str PostScript-Schriftname
font_size float Schriftgröße in Punkt
font_weight str Strichstärke ("thin", "light", "normal", "medium", "semi-bold", "bold", "extra-bold", "black")
is_italic bool Ob das Zeichen kursiv ist
color tuple[float, float, float] RGB-Farbe (r, g, b), Werte 0.0–1.0
rotation_degrees float Zeichendrehung in Grad
origin_x float X-Position des Textursprungs
origin_y float Y-Position des Textursprungs
advance_width float Vorschubbreite der Glyphe
mcid `int None`

Beispiel

from pdf_oxide import PdfDocument

doc = PdfDocument("paper.pdf")
chars = doc.extract_chars(0)

for ch in chars[:5]:
    print(f"'{ch.char}' at bbox={ch.bbox} "
          f"font={ch.font_name} size={ch.font_size:.1f} "
          f"weight={ch.font_weight} italic={ch.is_italic}")

TextSpan

Repräsentiert einen Textlauf mit gleicher Schrift und gleichem Stil. Wird von PdfDocument.extract_spans() zurückgegeben.

Attribut Typ Beschreibung
text str Der Textinhalt
bbox tuple[float, float, float, float] Begrenzungsrahmen (x0, y0, x1, y1)
font_name str PostScript-Schriftname
font_size float Schriftgröße in Punkt
is_bold bool Ob der Span fett ist
is_italic bool Ob der Span kursiv ist
is_monospace bool Ob die Schrift dicktengleich ist (Courier, Consolas usw.)
char_widths list[float] Vorschubbreiten pro Glyphe für exakte Begrenzungsrahmen
color tuple[float, float, float] RGB-Farbe (r, g, b), Werte 0.0–1.0

Beispiel

from pdf_oxide import PdfDocument

doc = PdfDocument("paper.pdf")
spans = doc.extract_spans(0)

for span in spans:
    print(f"'{span.text}' font={span.font_name} size={span.font_size:.1f} "
          f"bold={span.is_bold} italic={span.is_italic} color={span.color}")

Bildextraktion

extract_images() gibt ImageInfo-Objekte mit Bildmetadaten zurück. Verwenden Sie extract_image_bytes() für rohe Bilddaten, die sich zum Speichern auf der Festplatte eignen.

Rückgabeformat von extract_image_bytes()

Jedes von extract_image_bytes() zurückgegebene Dict hat folgende Schlüssel:

Schlüssel Typ Beschreibung
width int Bildbreite in Pixeln
height int Bildhöhe in Pixeln
data bytes Rohe Bilddaten
format str Bildformat (z. B. "png", "jpeg")

Beispiel

from pdf_oxide import PdfDocument

doc = PdfDocument("brochure.pdf")
images = doc.extract_image_bytes(0)

for i, img in enumerate(images):
    print(f"Image {i}: {img['width']}x{img['height']}")
    with open(f"image_{i}.{img['format']}", "wb") as f:
        f.write(img["data"])

SearchResult

Repräsentiert einen Text-Suchtreffer. Wird von search() und search_page() zurückgegeben.

Attribut Typ Beschreibung
page int Nullbasierter Seitenindex
text str Gefundener Text
x float X-Position in PDF-Punkten
y float Y-Position in PDF-Punkten

FormField

Repräsentiert ein Formularfeld. Wird von PdfDocument.get_form_fields() zurückgegeben.

Property Typ Beschreibung
name str Vollständig qualifizierter Feldname
field_type str Feldtyp: "text", "button", "choice", "signature" oder "unknown"
value `str bool
tooltip `str None`
bounds `tuple[float, float, float, float] None`
flags `int None`
max_length `int None`
is_readonly bool Ob das Feld schreibgeschützt ist
is_required bool Ob das Feld erforderlich ist

TextWord

Ein wortgruppierter Textlauf. Wird von PdfDocument.extract_words() und PdfPageRegion.extract_words() zurückgegeben.

Property Typ Beschreibung
text str Der Worttext
bbox tuple[float, float, float, float] Begrenzungsrahmen (x0, y0, x1, y1)
font_name str PostScript-Schriftname
font_size float Schriftgröße in Punkt
is_bold bool Ob das Wort fett ist
is_italic bool Ob das Wort kursiv ist
chars list[TextChar] Bestandteilzeichen

TextLine

Ein zeilengruppierter Textlauf. Wird von PdfDocument.extract_text_lines() und PdfPageRegion.extract_text_lines() zurückgegeben.

Property Typ Beschreibung
text str Der Zeilentext
bbox tuple[float, float, float, float] Begrenzungsrahmen (x0, y0, x1, y1)
words list[TextWord] Wörter in der Zeile
chars list[TextChar] Zeichen in der Zeile

PdfPageRegion

Ein zugeschnittener Bereich einer Seite. Wird von PdfDocument.within() und PdfPage.region() zurückgegeben.

Property Typ Beschreibung
bbox tuple[float, float, float, float] Die Grenzen des Bereichs

Methoden

region.extract_text() -> str
region.extract_words() -> list[TextWord]
region.extract_text_lines() -> list[TextLine]
region.extract_tables(table_settings: dict | None = None) -> list[dict]
region.extract_images() -> list
region.extract_paths() -> list

Extraktionsmethoden, die auf den Begrenzungsrahmen des Bereichs beschränkt sind.

LayoutParams

Berechnete adaptive Layout-Parameter für eine Seite. Wird von PdfDocument.page_layout_params() zurückgegeben.

Property Typ Beschreibung
word_gap_threshold float Schwelle für den Wortzwischenraum in Punkt
line_gap_threshold float Schwelle für den Zeilenzwischenraum in Punkt
median_char_width float Mittlere Zeichenbreite
median_font_size float Mittlere Schriftgröße
median_line_spacing float Mittlerer Zeilenabstand
column_count int Erkannte Anzahl von Textspalten

ExtractionProfile

Ein anpassbares Textextraktions-Profil, das an extract_words() / extract_text_lines() übergeben wird.

from pdf_oxide import ExtractionProfile

Statische Konstruktoren

ExtractionProfile.conservative()
ExtractionProfile.aggressive()
ExtractionProfile.balanced()
ExtractionProfile.academic()
ExtractionProfile.policy()
ExtractionProfile.form()
ExtractionProfile.government()
ExtractionProfile.scanned_ocr()
ExtractionProfile.adaptive()
ExtractionProfile.available() -> list[str]   # names of all built-in profiles

Properties

Property Typ Beschreibung
name str Profilname
tj_offset_threshold float Wortumbruch-Schwelle für TJ-Array-Offsets
word_margin_ratio float Wortrand-Verhältnis
space_threshold_em_ratio float Schwelle der Leerzeichenbreite (em-Verhältnis)
space_char_multiplier float Leerzeichen-Multiplikator
use_adaptive_threshold bool Ob adaptive Schwellen aktiviert sind

OfficeConverter

Konvertiert Office-Dokumente (DOCX, XLSX, PPTX) in PDF. Erfordert das office-Feature im Rust-Build.

from pdf_oxide import OfficeConverter

OfficeConverter()   # instances are stateless; the conversion methods are also usable as static methods

Methoden

OfficeConverter.from_docx(path: str) -> Pdf

Konvertiert ein Word-Dokument in ein Pdf-Objekt.

OfficeConverter.from_docx_bytes(data: bytes) -> Pdf

Konvertiert Word-Dokument-Bytes in ein Pdf-Objekt.

OfficeConverter.from_xlsx(path: str) -> Pdf

Konvertiert ein Excel-Tabellenblatt in ein Pdf-Objekt.

OfficeConverter.from_xlsx_bytes(data: bytes) -> Pdf

Konvertiert Excel-Tabellenblatt-Bytes in ein Pdf-Objekt.

OfficeConverter.from_pptx(path: str) -> Pdf

Konvertiert eine PowerPoint-Präsentation in ein Pdf-Objekt.

OfficeConverter.from_pptx_bytes(data: bytes) -> Pdf

Konvertiert PowerPoint-Präsentations-Bytes in ein Pdf-Objekt.

OfficeConverter.convert(path: str) -> Pdf

Erkennt das Format automatisch und konvertiert jedes unterstützte Office-Dokument in ein Pdf-Objekt.

Beispiel

from pdf_oxide import OfficeConverter

pdf = OfficeConverter.from_docx("report.docx")
pdf.save("report.pdf")

# Or use convert() for auto-detection
pdf = OfficeConverter.convert("spreadsheet.xlsx")
pdf.save("spreadsheet.pdf")

Grafikklassen

Diese Klassen stehen für die erweiterte PDF-Erstellung mit Grafiken zur Verfügung:

Color

from pdf_oxide import Color

Color(r: float, g: float, b: float)  # RGB, values 0.0-1.0
Color.from_hex("#ff0000")
Color.black()
Color.white()
Color.red()
Color.green()
Color.blue()

BlendMode

from pdf_oxide import BlendMode

BlendMode.NORMAL()
BlendMode.MULTIPLY()
BlendMode.SCREEN()
BlendMode.OVERLAY()
BlendMode.DARKEN()
BlendMode.LIGHTEN()
BlendMode.COLOR_DODGE()
BlendMode.COLOR_BURN()
BlendMode.HARD_LIGHT()
BlendMode.SOFT_LIGHT()
BlendMode.DIFFERENCE()
BlendMode.EXCLUSION()

ExtGState

from pdf_oxide import ExtGState

gs = ExtGState()
gs = gs.fill_alpha(0.5)
gs = gs.stroke_alpha(0.8)
gs = gs.alpha(0.5)  # Set both fill and stroke
gs = gs.blend_mode(BlendMode.MULTIPLY())

gs = ExtGState.semi_transparent()  # Preset

LineCap / LineJoin

from pdf_oxide import LineCap, LineJoin

LineCap.BUTT()       # Default
LineCap.ROUND()
LineCap.SQUARE()

LineJoin.MITER()     # Default
LineJoin.ROUND()
LineJoin.BEVEL()

Verläufe

from pdf_oxide import LinearGradient, RadialGradient, Color

# Linear gradient (fluent API)
grad = (LinearGradient()
    .start(0, 0)
    .end(100, 0)
    .add_stop(0.0, Color.red())
    .add_stop(1.0, Color.blue()))

# Convenience constructors
hgrad = LinearGradient.horizontal(200, Color.red(), Color.blue())
vgrad = LinearGradient.vertical(100, Color(1, 1, 0), Color(0, 0, 1))

# Radial gradient
rgrad = RadialGradient.centered(50, 50, 50)
rgrad = rgrad.add_stop(0.0, Color(1, 1, 0))
rgrad = rgrad.add_stop(1.0, Color(1, 0, 0))

PatternPresets

from pdf_oxide import PatternPresets, Color

PatternPresets.horizontal_stripes(width, height, stripe_height, color)
PatternPresets.vertical_stripes(width, height, stripe_width, color)
PatternPresets.checkerboard(size, color1, color2)
PatternPresets.dots(spacing, radius, color)
PatternPresets.diagonal_lines(size, line_width, color)
PatternPresets.crosshatch(size, line_width, color)

OCR-Klassen

Erfordert das ocr-Feature im Rust-Build.

OcrEngine

from pdf_oxide import OcrEngine, OcrConfig

engine = OcrEngine(
    det_model_path: str,
    rec_model_path: str,
    dict_path: str,
    config: OcrConfig | None = None
)

OcrConfig

from pdf_oxide import OcrConfig

config = OcrConfig(
    det_threshold: float | None = None,
    box_threshold: float | None = None,
    rec_threshold: float | None = None,
    num_threads: int | None = None,
    max_candidates: int | None = None,
    use_v5: bool = False
)

DocumentBuilder

Fluent Builder zum seitenweisen Zusammensetzen von PDFs. Siehe das Beispiel unten und Von Grund auf erstellen.

from pdf_oxide import DocumentBuilder

Methoden auf Dokumentebene

Methode Parameter Beschreibung
DocumentBuilder() – Einen neuen Builder erzeugen
title(title) str Dokumenttitel setzen
author(author) str Dokumentautor setzen
subject(subject) str Dokumentbetreff setzen
keywords(keywords) str Dokumentschlüsselwörter setzen
creator(creator) str Den Namen der erzeugenden Anwendung setzen
on_open(script) str Eine dokumentweite Open-JavaScript-Aktion setzen
tagged_pdf_ua1() – Ein barrierefreies Tagged PDF/UA-1-Dokument ausgeben
language(lang) str Die Dokumentsprache setzen (z. B. "en-US")
role_map(custom, standard) str, str Ein benutzerdefiniertes Struktur-Tag auf ein Standard-Tag abbilden
register_embedded_font(name, font) str, EmbeddedFont Eine Schrift registrieren (konsumiert die EmbeddedFont)

Seiten-Factories

builder.a4_page() -> FluentPageBuilder       # 595 x 842 pt
builder.letter_page() -> FluentPageBuilder   # 612 x 792 pt
builder.page(width: float, height: float) -> FluentPageBuilder

Ausgabe

builder.build() -> bytes
builder.save(path: str) -> None
builder.save_encrypted(path: str, user_password: str, owner_password: str) -> None
builder.to_bytes_encrypted(user_password: str, owner_password: str) -> bytes

FluentPageBuilder

Puffert Operationen auf Seitenebene bis done(). Wird von DocumentBuilder.a4_page() / letter_page() / page() zurückgegeben. Jede Methode gibt self für die Verkettung zurück; done() schließt die Seite ab und gibt den übergeordneten DocumentBuilder zurück.

Text & Layout

Methode Parameter Beschreibung
font(name, size) str, float Aktuelle Schrift und Größe setzen
at(x, y) float, float Den Cursor an eine absolute Position bewegen
text(text) str Text am Cursor zeichnen
heading(level, text) int, str Eine Überschrift zeichnen (Stufe 1–6)
paragraph(text) str Einen umgebrochenen Absatz zeichnen
space(points) float Vertikalen Abstand vorschieben
horizontal_rule() – Eine horizontale Trennlinie zeichnen
columns(column_count, gap_pt, text) int, float, str Ausgeglichener mehrspaltiger Textfluss
footnote(ref_mark, note_text) str, str Inline-Referenzzeichen + Notiz am Seitenende
new_page_same_size() – Eine neue Seite mit denselben Maßen beginnen
measure(text) -> float str Die gerenderte Textbreite in Punkt messen
remaining_space() -> float – Verbleibender vertikaler Raum auf der Seite

Inline-Läufe

page.inline(text: str)
page.inline_bold(text: str)
page.inline_italic(text: str)
page.inline_color(text: str, r: float, g: float, b: float)
page.newline()

page.link_url(url: str)
page.link_page(page: int)
page.link_named(name: str)
page.link_javascript(script: str)
page.on_open(script: str)
page.on_close(script: str)
page.field_keystroke(script: str)
page.field_format(script: str)
page.field_validate(script: str)
page.field_calculate(script: str)

Markup-Anmerkungen

page.highlight(color: tuple[float, float, float])
page.underline(color: tuple[float, float, float])
page.strikeout(color: tuple[float, float, float])
page.squiggly(color: tuple[float, float, float])
page.sticky_note(text: str)
page.sticky_note_at(x: float, y: float, text: str)
page.watermark(text: str)
page.watermark_confidential()
page.watermark_draft()
page.stamp(name: str)
page.freetext(x: float, y: float, w: float, h: float, text: str)

AcroForm-Widgets

page.text_field(name: str, x: float, y: float, w: float, h: float, default_value: str | None = None)
page.checkbox(name: str, x: float, y: float, w: float, h: float, checked: bool = False)
page.combo_box(name: str, x: float, y: float, w: float, h: float, options: list[str], selected: str | None = None)
page.radio_group(name: str, buttons: list[tuple[str, float, float, float, float]], selected: str | None = None)
page.push_button(name: str, x: float, y: float, w: float, h: float, caption: str)
page.signature_field(name: str, x: float, y: float, w: float, h: float)

Grafik

page.rect(x: float, y: float, w: float, h: float)
page.filled_rect(x: float, y: float, w: float, h: float, r: float, g: float, b: float)
page.line(x1: float, y1: float, x2: float, y2: float)
page.text_in_rect(x: float, y: float, w: float, h: float, text: str, align: int | None = None)
page.stroke_rect(x, y, w, h, width=1.0, color=(0.0, 0.0, 0.0))
page.stroke_rect_dashed(x, y, w, h, dash, width=1.0, color=(0.0, 0.0, 0.0), phase=0.0)
page.stroke_line(x1, y1, x2, y2, width=1.0, color=(0.0, 0.0, 0.0))
page.stroke_line_dashed(x1, y1, x2, y2, dash, width=1.0, color=(0.0, 0.0, 0.0), phase=0.0)

Bilder & Barcodes

page.image_with_alt(bytes: bytes, x: float, y: float, w: float, h: float, alt_text: str)
page.image_artifact(bytes: bytes, x: float, y: float, w: float, h: float)
page.barcode_1d(barcode_type: int, data: str, x: float, y: float, w: float, h: float)
page.barcode_qr(data: str, x: float, y: float, size: float)

barcode_type: 0=Code128, 1=Code39, 2=EAN13, 3=EAN8, 4=UPCA, 5=ITF, 6=Code93, 7=Codabar.

Tabellen

page.table(table: Table)
page.streaming_table(
    columns: list[Column],
    repeat_header: bool = False,
    mode: str = "fixed",
    sample_rows: int = 50,
    min_col_width_pt: float = 20.0,
    max_col_width_pt: float = 400.0,
    max_rowspan: int = 1,
    batch_size: int = 256
) -> StreamingTable

Commit

page.done() -> DocumentBuilder

EmbeddedFont

Eine bei einem DocumentBuilder registrierte TTF-/OTF-Schrift.

from pdf_oxide import EmbeddedFont

EmbeddedFont.from_file(path: str) -> EmbeddedFont
EmbeddedFont.from_bytes(data: bytes, name: str | None = None) -> EmbeddedFont
Property Typ Beschreibung
name str Der registrierte Name der Schrift

Tabellen

Value Objects für die fluent Tabellen-API.

Align

from pdf_oxide import Align

Align.LEFT     # 0
Align.CENTER   # 1
Align.RIGHT    # 2

Column

from pdf_oxide import Column

Column(header: str, width: float = 100.0, align: Align | int | None = None)
Property Typ Beschreibung
header str Spaltenüberschrift
width float Spaltenbreite in Punkt
align int Zellenausrichtung

Table

from pdf_oxide import Table

Table(columns: list[Column], rows: list[list[str]], has_header: bool = False)

Eine gepufferte Tabelle, die von FluentPageBuilder.table() konsumiert wird. Mit has_header=True werden die Spaltenüberschriften als formatierte Kopfzeile gerendert.

StreamingTable

Ein zeilenstreamendes Tabellen-Handle, das von FluentPageBuilder.streaming_table() zurückgegeben wird — für Tabellen, die zu groß sind, um auf einmal materialisiert zu werden.

Methode Parameter Beschreibung
push_row(cells) list[str] Eine Zeile aus Zellen-Strings anhängen
push_row_span(cells) list[tuple[str, int]] Eine Zeile aus (text, colspan)-Zellen anhängen
flush() – Den aktuellen Batch leeren
finish() – Die Tabelle abschließen und den FluentPageBuilder zurückgeben
column_count() – → int Anzahl der Spalten
pending_row_count() – → int Gepufferte, aber noch nicht festgeschriebene Zeilen
batch_count() – → int Anzahl der abgeschlossenen Batches

Seitenvorlagen

Wiederkehrende Kopf-/Fußzeilen-Artefakte, die über Seiten hinweg angewendet werden.

Artifact / ArtifactStyle

from pdf_oxide import Artifact, ArtifactStyle

Artifact()                       # empty artifact
Artifact.center(text: str)       # centered artifact text
artifact.with_left(text: str)    # add left-aligned text

style = ArtifactStyle()
style = style.font(name: str, size: float)
style = style.bold()

from pdf_oxide import Header, Footer

Header()                  # or Header.center(text: str)
Footer()                  # or Footer.center(text: str)

PageTemplate

from pdf_oxide import PageTemplate, Header, Footer

template = (PageTemplate()
    .header(Header.center("Confidential"))
    .footer(Footer.center("Page")))

Digitale Signaturen

PDFs signieren, mit Zeitstempel versehen und verifizieren (PAdES / LTV). Erfordert die Features signatures (und optional tsa-client) im Rust-Build.

Certificate

from pdf_oxide import Certificate

Certificate.load(data: bytes) -> Certificate                       # DER certificate (verify only)
Certificate.load_pem(cert_pem: str, key_pem: str) -> Certificate   # signing credential
Certificate.load_pkcs12(data: bytes, password: str) -> Certificate # PKCS#12 / .p12 signing credential
Methode Rückgabe Beschreibung
subject() str Subject-DN des Zertifikats
issuer() str Issuer-DN des Zertifikats
serial() str Seriennummer
validity() tuple[int, int] (not_before, not_after) Unix-Zeitstempel
is_valid() bool Ob sich das Zertifikat derzeit innerhalb seines Gültigkeitsfensters befindet

Signature

Wird von PdfDocument.signatures() zurückgegeben.

Property / Methode Typ Beschreibung
signer_name `str None`
reason `str None`
location `str None`
contact_info `str None`
signing_time `int None`
covers_whole_document bool Ob die Signatur die gesamte Datei abdeckt
pades_level PadesLevel Erkannte PAdES-Baseline (B-B/B-T/B-LT)
verify() bool Die Signatur kryptografisch verifizieren
verify_detached(pdf_data) bool Verifizieren einschließlich des messageDigest gegen die Datei-Bytes

Timestamp

from pdf_oxide import Timestamp

Timestamp.parse(data: bytes) -> Timestamp
Property / Methode Typ Beschreibung
time int Zeitstempel-Zeit (Unix)
serial str Seriennummer der TSA-Antwort
policy_oid str TSA-Policy-OID
tsa_name str TSA-Name
hash_algorithm int Code des Hash-Algorithmus des Message-Imprints
message_imprint bytes Das gehashte Message-Imprint
verify() bool Das Zeitstempel-Token verifizieren

TsaClient

from pdf_oxide import TsaClient

client = TsaClient(
    url: str,
    username: str | None = None,
    password: str | None = None,
    timeout_seconds: int = 30,
    hash_algorithm: int = 2,
    use_nonce: bool = True,
    cert_req: bool = True
)
client.request_timestamp(data: bytes) -> Timestamp
client.request_timestamp_hash(digest: bytes, algorithm: int = 2) -> Timestamp

PadesLevel

from pdf_oxide import PadesLevel

PadesLevel.B_B     # baseline
PadesLevel.B_T     # + trusted timestamp
PadesLevel.B_LT    # + long-term validation material
PadesLevel.B_LTA   # + archival timestamp

RevocationMaterial

from pdf_oxide import RevocationMaterial

RevocationMaterial(
    certs: list[bytes] | None = None,
    crls: list[bytes] | None = None,
    ocsps: list[bytes] | None = None
)

DER-codierte Zertifikate, CRLs und OCSP-Antworten für die B-LT-Signierung.

Dss

Ein geparster Document Security Store, der von PdfDocument.dss() zurückgegeben wird.

Property Typ Beschreibung
certs list[bytes] Dokumentweite Zertifikat-DER-Blobs
crls list[bytes] CRL-DER-Blobs
ocsps list[bytes] OCSP-Antwort-DER-Blobs
vri list[str] VRI-Schlüssel pro Signatur (hexadezimaler SHA-1 von /Contents)

Funktionen auf Modulebene

from pdf_oxide import (
    sign_pdf_bytes, sign_pdf_bytes_pades, has_document_timestamp,
    generate_barcode_svg, generate_qr_svg,
    plan_split_by_bookmarks, split_by_bookmarks,
)

Signieren

sign_pdf_bytes(pdf_data: bytes, cert: Certificate, reason: str | None = None, location: str | None = None) -> bytes

Signiert rohe PDF-Bytes mit einem geladenen Signier-Certificate und gibt die signierte PDF zurück.

sign_pdf_bytes_pades(
    pdf_data: bytes,
    cert: Certificate,
    level: PadesLevel,
    tsa_url: str | None = None,
    reason: str | None = None,
    location: str | None = None,
    revocation: RevocationMaterial | None = None
) -> bytes

Signiert rohe PDF-Bytes auf einer PAdES-Baseline-Stufe. B_T/B_LT erfordern eine tsa_url.

has_document_timestamp(pdf_data: bytes) -> bool

Ob die PDF einen dokumentweiten RFC-3161-Archivzeitstempel (PAdES-B-LTA) trägt.

Barcodes

generate_barcode_svg(barcode_type: int, data: str) -> str
generate_qr_svg(data: str, error_correction: int, size: int) -> str

Erzeugt einen 1D-Barcode oder QR-Code als SVG-String. Erfordert das barcodes-Feature.

Anhand von Lesezeichen aufteilen

plan_split_by_bookmarks(src_bytes: bytes, title_prefix: str | None = None, ignore_case: bool = False, level: int = 1, include_front_matter: bool = True) -> list[dict]
split_by_bookmarks(src_bytes: bytes, title_prefix: str | None = None, ignore_case: bool = False, level: int = 1, include_front_matter: bool = True) -> list[tuple[dict, bytes]]

Plant oder führt eine Aufteilung einer PDF an Lesezeichengrenzen durch. plan_* gibt nur Segment-Metadaten zurück; split_* gibt jedes Segment zusammen mit seinen PDF-Bytes zurück.

OCR-Modellbereitstellung

prefetch_models(languages: list[str]) -> str
model_manifest() -> str
prefetch_available() -> bool

Stellt OCR-Modelle für die Offline-/Air-Gap-Nutzung bereit, inspiziert das Modell-Manifest (JSON) und prüft, ob dieser Build Modelle herunterladen kann.

Logging

setup_logging() -> None
set_log_level(level: str) -> None     # "off" | "error" | "warn" | "info" | "debug" | "trace"
get_log_level() -> str
disable_logging() -> None

Engine-Tuning

set_max_ops_per_stream(limit: int | None) -> int | None
set_preserve_unmapped_glyphs(preserve: bool) -> bool

Passt die Operator-Obergrenze pro Stream (Schutz vor adversen Eingaben) und die U+FFFD-Erhaltung für nicht zugeordnete Glyphen an. Beide geben den vorherigen Wert zurück.

Kryptografische Governance

crypto_active_provider() -> str
crypto_available_providers() -> list[str]
crypto_use_fips() -> None                 # install the FIPS aws-lc-rs provider (requires the fips feature)
crypto_set_policy(spec: str) -> None      # e.g. "strict" or "compat;deny:rc4@write"
crypto_policy() -> str
crypto_inventory() -> list[str]
crypto_cbom() -> str                      # CycloneDX 1.6 CBOM (JSON)

Asynchrone API

async/await-Wrapper, die blockierende Operationen in einem Thread-Pool ausführen. Die Methoden spiegeln ihre synchronen Gegenstücke wider.

from pdf_oxide import AsyncPdfDocument, AsyncPdf, AsyncOfficeConverter

async def main():
    doc = await AsyncPdfDocument.open("input.pdf")
    text = await doc.extract_text(0)
    await doc.close()
    # Or use as an async context manager:
    async with await AsyncPdfDocument.from_bytes(pdf_bytes) as doc:
        md = await doc.to_markdown_all()
Klasse Konstruktoren Hinweise
AsyncPdfDocument await AsyncPdfDocument.open(path, password=None), await AsyncPdfDocument.from_bytes(data, password=None) Alle PdfDocument-Methoden sind als Awaitables verfügbar; unterstützt async with und .close()
AsyncPdf umschließt Pdf-Factory-Methoden await pdf.save(path), await pdf.to_bytes()
AsyncOfficeConverter umschließt die statischen OfficeConverter-Methoden z. B. await AsyncOfficeConverter.from_docx(path)

Fehlerbehandlung

PdfError

Alle PDF-spezifischen Fehler lösen PdfError aus:

from pdf_oxide import PdfDocument, PdfError

try:
    doc = PdfDocument("file.pdf")
    text = doc.extract_text(0)
except PdfError as e:
    print(f"PDF error: {e}")
except FileNotFoundError:
    print("File not found")
except IndexError:
    print("Page index out of range")

Häufige Fehlerszenarien:

Ausnahme Ursache
PdfError Fehlerhafte PDF, verschlüsselt ohne Passwort, Parse-Fehler
FileNotFoundError Datei existiert nicht
IndexError Seitenindex überschreitet page_count()
ValueError Ungültiges Argument (z. B. negativer Seitenindex)

Vollständiges Beispiel

from pdf_oxide import PdfDocument, Pdf

# --- Extraction ---
doc = PdfDocument("input.pdf")
print(f"Pages: {doc.page_count()}")

for i in range(doc.page_count()):
    text = doc.extract_text(i)
    print(f"Page {i + 1}: {len(text)} characters")

# Character-level analysis
chars = doc.extract_chars(0)
fonts = set(ch.font_name for ch in chars)
print(f"Fonts on page 1: {fonts}")

# Image extraction
images = doc.extract_image_bytes(0)
for i, img in enumerate(images):
    with open(f"extracted_{i}.{img['format']}", "wb") as f:
        f.write(img["data"])

# --- Creation ---
pdf = Pdf.from_markdown("# Report\n\nGenerated by PDF Oxide.",
                        title="Report", author="PDF Oxide")
pdf.save("report.pdf")

# --- Editing ---
doc = PdfDocument("document.pdf")
doc.set_title("Updated Title")
doc.set_author("New Author")
doc.rotate_all_pages(90)

# Search and replace via DOM
page = doc.page(0)
for text in page.find_text_containing("DRAFT"):
    page.set_text(text.id, "FINAL")
doc.save_page(page)

# Form filling
fields = doc.get_form_fields()
for f in fields:
    print(f"{f.name} ({f.field_type}) = {f.value}")
doc.set_form_field_value("name", "John Doe")

# Merge another PDF
merged_count = doc.merge_from("appendix.pdf")
print(f"Merged {merged_count} pages")

doc.save("output.pdf")

# --- Search ---
results = doc.search("configuration", case_insensitive=True)
for r in results:
    print(f"Page {r.page + 1}: '{r.text}' at ({r.x:.0f}, {r.y:.0f})")

Ergänzungen in v0.3.38

DocumentBuilder / FluentPageBuilder / EmbeddedFont

from pdf_oxide import DocumentBuilder, EmbeddedFont, StampType

font = EmbeddedFont.from_file("DejaVuSans.ttf")
# Alt: EmbeddedFont.from_bytes(data: bytes, name: str | None = None)

(DocumentBuilder()
    .register_embedded_font("DejaVu", font)
    .letter_page()           # or .a4_page() / .page(size)
        .at(72, 720).font("DejaVu", 12).text("Hello")
        .heading(1, "Title")
        .paragraph("Body text with automatic wrapping")
        # Annotations (15 methods)
        .link_url("https://example.com")
        .link_page(2)
        .link_named("glossary")
        .highlight((1.0, 1.0, 0.0))
        .underline((0.0, 0.0, 1.0))
        .strikeout((1.0, 0.0, 0.0))
        .squiggly((1.0, 0.5, 0.0))
        .sticky_note("Review this")
        .stamp(StampType.APPROVED)
        .freetext((100, 500, 200, 50), "Comment")
        .watermark("DRAFT")
        .watermark_confidential()
        .watermark_draft()
        # AcroForm widgets (5 types)
        .text_field("name", 150, 400, 200, 20, "Jane Doe")
        .checkbox("agree", 72, 380, 15, 15, True)
        .combo_box("country", 150, 360, 200, 20, ["US", "UK"], "US")
        .radio_group("tier", [("free", 72, 340, 15, 15), ("pro", 120, 340, 15, 15)], "pro")
        .push_button("submit", 72, 300, 80, 25, "Submit")
        # Graphics primitives
        .rect(50, 270, 500, 2)
        .filled_rect(50, 260, 500, 2, (0.9, 0.9, 0.9))
        .line(50, 250, 550, 250)
    .done()
    .save_encrypted("out.pdf", "user-pw", "owner-pw"))
# Alt: .save("out.pdf") / .build() -> bytes
# Alt: .to_bytes_encrypted("user-pw", "owner-pw") -> bytes

HTML- + CSS-Pipeline

Pdf.from_html_css(html: str, css: str, font_bytes: bytes) -> Pdf
Pdf.from_html_css_with_fonts(html: str, css: str, fonts: list[tuple[str, bytes]]) -> Pdf

Siehe Aus HTML erstellen.

Signaturverifizierung

from pdf_oxide import PdfDocument, Timestamp, TsaClient

doc = PdfDocument("signed.pdf")
doc.signature_count()                # int
for sig in doc.signatures():
    sig.signer_name                  # str
    sig.reason                       # str | None
    sig.location                     # str | None
    sig.signing_time                 # datetime | None
    sig.verify()                     # "Valid" | "Invalid" | "Unknown"
    sig.verify_detached(pdf_bytes)   # adds messageDigest check

# Timestamp
ts = Timestamp.parse(tst_bytes)
ts.time, ts.serial, ts.policy_oid, ts.tsa_name, ts.hash_algorithm, ts.message_imprint

# TSA client (behind `tsa-client` feature)
client = TsaClient(url="https://freetsa.org/tsr",
                   username=None, password=None,
                   timeout_seconds=30, hash_algorithm=2,
                   use_nonce=True, cert_req=True)
ts = client.request_timestamp(pdf_bytes)
ts = client.request_timestamp_hash(digest, algorithm=2)

Details siehe Digitale Signaturen.

Rendering

doc.render_page_region(page: int, x: float, y: float, w: float, h: float, format: int = 0) -> bytes
doc.render_page_fit(page: int, fit_width: int, fit_height: int, format: int = 0) -> bytes

format: 0 = PNG, 1 = JPEG. Koordinaten in PDF-Punkten ab der unteren linken Ecke.

Pdf-Flatten

doc.flatten_to_images(dpi: int = 150) -> bytes

Other Language Bindings

PDF Oxide bietet native Bindings für jedes wichtige Ökosystem: Rust, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C und Elixir.

Nächste Schritte