Skip to content
PDF Oxide

Справочник Python API

PDF Oxide предоставляет нативные привязки для Python, собранные с помощью PyO3. Готовые wheel-пакеты доступны для Python 3.8–3.14 на Linux, macOS и Windows (x86_64 и ARM64).

pip install pdf_oxide

Описание Rust API см. в справочнике Rust API. Описание JavaScript API см. в справочнике Node.js API или справочнике WASM API. Подробности о типах см. в разделе Типы и перечисления.

PdfDocument

Основной класс для открытия, извлечения, редактирования и сохранения PDF-файлов.

from pdf_oxide import PdfDocument

Конструктор

PdfDocument(path: str, password: str | None = None)
Параметр Тип Описание
path str Путь к PDF-файлу
password str | None Необязательный пароль для зашифрованных PDF (по умолчанию None)

Передайте password=, чтобы открыть зашифрованный PDF за один шаг. В качестве альтернативы можно вызвать doc.authenticate(password) уже после открытия.

Выбрасывает FileNotFoundError, если файл не существует. Выбрасывает PdfError, если файл не является корректным PDF.

Методы класса

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

Открывает PDF из байтов в памяти (например, загруженных из S3 или полученных по HTTP). Принимает необязательный пароль для зашифрованных PDF.

Параметр Тип Описание
data bytes Сырые байты PDF-файла
password str | None Необязательный пароль для зашифрованных PDF (по умолчанию 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")

Методы

Общие

Метод Тип возврата Описание
version() tuple[int, int] Версия PDF в виде (major, minor) (например, (1, 7))
authenticate(password) bool Аутентификация зашифрованного PDF с паролем пользователя или владельца

Сведения о документе

doc.page_count() -> int

Возвращает количество страниц в документе.

doc.has_structure_tree() -> bool

Проверяет, является ли документ тегированным PDF (Tagged PDF) с деревом структуры.

Аутентификация

doc.authenticate(password: str) -> bool

Аутентификация с паролем после открытия. Возвращает True, если аутентификация прошла успешно.

Извлечение текста

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

Извлекает простой текст с одной страницы. Отсчёт страниц ведётся от нуля. При необходимости можно ограничить область region, исключить именованные слои необязательного содержимого (optional content) или красители/сепарации по имени, а также включить или отключить реконструкцию таблиц.

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]

Извлекает позиционирование каждого символа и метаданные шрифта. Возвращает список объектов TextChar.

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

Извлекает текстовые спаны с метаданными шрифта. Каждый спан — это последовательность текста с одинаковым стилем. Для многоколоночных PDF передайте reading_order="column_aware".

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]

Извлекает текст, сгруппированный по словам, с ограничивающими прямоугольниками. Возвращает список объектов TextWord.

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]

Извлекает текст, сгруппированный по строкам. Возвращает список объектов TextLine.

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

Извлекает спаны, символы и размеры страницы за один проход. Возвращает словарь с ключами spans, chars, page_width, page_height, text. Эффективнее, чем раздельный вызов extract_spans() + extract_chars().

doc.page_layout_params(page: int) -> LayoutParams

Вычисляет адаптивные параметры компоновки (пороги межсловных и межстрочных интервалов, медианные метрики, число колонок) для страницы. См. LayoutParams.

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

Создаёт дескриптор обрезанной области для извлечения текста, слов, строк, таблиц, изображений и контуров внутри bbox. См. PdfPageRegion.

Авто-извлечение и классификация

doc.extract_text_auto(page: int) -> str

Автоматически выбирает оптимальную стратегию извлечения (нативный текст или OCR) для страницы и возвращает простой текст.

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

Автоматически извлекает страницу и возвращает JSON-документ; передайте строку options_json в формате JSON для тонкой настройки конвейера.

doc.classify_page(page: int) -> str

Классифицирует отдельную страницу (например, "text", "scanned", "mixed").

doc.classify_document() -> str

Классифицирует весь документ по выборке его страниц.

doc.has_text_layer(page: int) -> bool

Проверяет, есть ли у страницы извлекаемый нативный текстовый слой (в отличие от случая, когда требуется OCR).

Конвертация

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

Преобразует страницу в простой текст с опциями компоновки.

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

Преобразует все страницы в простой текст.

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

Преобразует страницу в 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

Преобразует все страницы в 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

Преобразует страницу в 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

Преобразует все страницы в HTML.

Конвертация в Office

Метод Тип возврата Описание
to_docx(path) – Преобразует PDF в файл документа Word
to_docx_bytes() bytes Преобразует PDF в байты DOCX
to_pptx(path) – Преобразует PDF в файл PowerPoint
to_pptx_bytes() bytes Преобразует PDF в байты PPTX
to_xlsx(path) – Преобразует PDF в файл книги Excel
to_xlsx_bytes() bytes Преобразует PDF в байты XLSX

Извлечение изображений

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

Извлекает все изображения со страницы, включая картинки из потоков содержимого и вложенных Form XObject.

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

Извлекает сырые байты изображений со страницы. Каждый словарь содержит width, height, data (байты) и format.

Поиск

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

Ищет текст по всем страницам. Установите max_results=0 для неограниченного числа результатов. Возвращает список совпадений с номером страницы, текстом и координатами.

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

Ищет текст на одной странице.

Редактирование метаданных

Метод Параметры Описание
set_title(title) str Задаёт заголовок документа
set_author(author) str Задаёт автора документа
set_subject(subject) str Задаёт тему документа
set_keywords(keywords) str Задаёт ключевые слова документа

Поворот страниц

Метод Параметры Возвращает Описание
page_rotation(page) int int Получить текущий поворот (0, 90, 180, 270)
set_page_rotation(page, degrees) int, int – Задать абсолютный поворот
rotate_page(page, degrees) int, int – Добавить к текущему повороту
rotate_all_pages(degrees) int – Повернуть все страницы

Размеры страниц

Метод Параметры Возвращает Описание
page_media_box(page) int tuple[float, float, float, float] Получить MediaBox (llx, lly, urx, ury)
set_page_media_box(page, llx, lly, urx, ury) int, float, float, float, float – Задать MediaBox
page_crop_box(page) int `tuple None`
set_page_crop_box(page, llx, lly, urx, ury) int, float, float, float, float – Задать CropBox
crop_margins(left, right, top, bottom) float, float, float, float – Обрезать поля всех страниц

Стирание / закрашивание

Метод Параметры Описание
erase_region(page, llx, lly, urx, ury) int, float, float, float, float Стереть прямоугольную область
erase_regions(page, rects) int, list[tuple] Стереть несколько областей
clear_erase_regions(page) int Очистить отложенные операции стирания

Аннотации

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

Получает метаданные аннотаций (тип, прямоугольник, содержимое и т. д.) для страницы.

Метод Параметры Возвращает Описание
flatten_page_annotations(page) int – Свести аннотации на странице
flatten_all_annotations() – – Свести все аннотации
is_page_marked_for_flatten(page) int bool Проверить, помечена ли страница для сведения
unmark_page_for_flatten(page) int – Снять с страницы пометку для сведения

Редакция

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

Помечает прямоугольную область для редакции с необязательным цветом заливки RGB.

doc.redaction_count(page: int) -> int

Возвращает количество отложенных редакций на странице.

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

Необратимо применяет все редакции, удаляя лежащее под ними содержимое и при необходимости очищая метаданные, JavaScript и вложенные файлы.

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

Очищает документ без редактирования областей: удаляет метаданные, JavaScript и/или вложенные файлы.

Метод Параметры Возвращает Описание
apply_page_redactions(page) int – Применить редакции на странице
apply_all_redactions() – – Применить все отложенные редакции
is_page_marked_for_redaction(page) int bool Проверить, помечена ли страница для редакции
unmark_page_for_redaction(page) int – Снять с страницы пометку для редакции

Слои и красители

Метод Параметры Возвращает Описание
get_layers() – list[str] Список имён слоёв необязательного содержимого (OCG)
get_page_inks(page) int list[str] Список имён красителей / сепараций на странице
get_page_inks_deep(page) int list[str] Список красителей, включая вложенные в Form XObject

Очистка колонтитулов

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

Обнаруживает и удаляет повторяющиеся верхние колонтитулы, нижние колонтитулы или артефакты страниц по всему документу. threshold — это доля повторений между страницами. Возвращает количество удалённых элементов.

Метод Параметры Описание
erase_header(page) int Стереть обнаруженную область верхнего колонтитула на странице
edit_header(page) int Пометить область верхнего колонтитула для редактирования
erase_footer(page) int Стереть обнаруженную область нижнего колонтитула на странице
edit_footer(page) int Пометить область нижнего колонтитула для редактирования
erase_artifacts(page) int Стереть обнаруженные артефакты на странице
sync_editor_erasures() – Сбросить отложенные стирания колонтитулов/артефактов в редактор

Поля форм

doc.get_form_fields() -> list[FormField]

Получает все поля форм. Свойства см. в FormField.

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

Получает значение поля формы по имени. Возвращает подходящий тип Python в зависимости от типа поля.

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

Задаёт значение поля формы по имени.

doc.has_xfa() -> bool

Проверяет, содержит ли документ формы XFA.

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

Экспортирует данные формы в файл. Поддерживаемые форматы: "fdf" и "xfdf".

Метод Параметры Описание
flatten_forms() – Свести все поля форм в содержимое страниц
flatten_forms_on_page(page) int Свести формы на конкретной странице

Манипуляции с изображениями

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

Получает имена и границы изображений для операций позиционирования. Каждый словарь содержит name, bounds [x, y, width, height] и matrix.

Метод Параметры Описание
reposition_image(page, name, x, y) int, str, float, float Переместить изображение
resize_image(page, name, width, height) int, str, float, float Изменить размер изображения
set_image_bounds(page, name, x, y, width, height) int, str, float, float, float, float Задать позицию и размер изображения
clear_image_modifications(page) int Очистить отложенные изменения изображений
has_image_modifications(page) int → bool Проверить наличие отложенных изменений изображений

Операции с документом

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

Объединяет страницы из другого PDF. Принимает путь к файлу или экземпляр PdfDocument. Возвращает количество объединённых страниц.

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

Прикрепляет файл к PDF.

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

Получает закладки документа / оглавление. Возвращает None, если структура отсутствует.

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

Получает векторные контуры (линии, кривые, фигуры) со страницы.

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

Получает выровненные по осям прямоугольники (из заливаемых/обводимых контуров) на странице.

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

Получает прямые отрезки линий на странице.

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

Обнаруживает и извлекает таблицы. Каждая таблица — это словарь со строками и ячейками (текст + ограничивающие прямоугольники). Передайте table_settings для тонкой настройки стратегии обнаружения.

doc.extract_structured(page: int) -> str

Извлекает страницу как структурированный JSON-документ (логический порядок чтения, блоки и роли).

doc.page_labels() -> list[dict]

Получает диапазоны меток страниц. Каждый словарь содержит start_page, style, prefix и start_value.

doc.xmp_metadata() -> dict | None

Получает метаданные XMP в виде словаря с полями вроде dc_title, dc_creator, xmp_create_date и т. д. Возвращает None, если метаданных XMP нет.

OCR

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

Извлекает текст с помощью OCR. Требует функции ocr в сборке Rust. Передайте собственный OcrEngine или None для движка по умолчанию.

Извлечение и переупорядочивание страниц

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

Извлекает указанные индексы страниц в новый PDF-файл по пути output.

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

Извлекает указанные индексы страниц в новый PDF, возвращаемый в виде байтов.

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

Извлекает один или несколько диапазонов страниц (start, end) в новый PDF, возвращаемый в виде байтов.

Метод Параметры Описание
select_pages(pages) list[int] Оставить только перечисленные страницы в заданном порядке
delete_page(index) int Удалить одну страницу
move_page(from_index, to_index) int, int Переместить страницу на новую позицию

Соответствие стандартам и валидация

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

Проверяет соответствие уровню PDF/A (например, "1b", "2b", "3b"). Возвращает словарь-отчёт.

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

Преобразует документ в PDF/A и возвращает словарь с отчётом о конвертации.

doc.validate_pdf_ua() -> dict

Проверяет соответствие требованиям PDF/UA (доступность).

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

Проверяет соответствие уровню PDF/X (полиграфическое производство).

Разрешения и предупреждения

doc.permissions() -> dict

Возвращает флаги разрешений шифрования документа (печать, копирование, изменение, аннотирование и т. д.).

doc.structured_warnings() -> list

Возвращает предупреждения, собранные при извлечении структурированного / тегированного содержимого.

doc.flatten_warnings() -> list[str]

Возвращает предупреждения, собранные при сведении форм/аннотаций.

Подписи и Document Security Store

doc.signatures() -> list[Signature]

Возвращает все цифровые подписи в документе. См. Signature.

doc.signature_count() -> int

Возвращает количество цифровых подписей.

doc.dss() -> Dss | None

Возвращает разобранный Document Security Store (материалы LTV) документа или None. См. Dss.

API страниц (v0.3.34)

PdfDocument поддерживает итерацию и индексирование, возвращая ленивые объекты Page. См. 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

doc.page(index: int) -> PdfPage

Получает DOM-подобный дескриптор страницы для поэлементного редактирования. См. PdfPage.

doc.save_page(page: PdfPage) -> None

Сохраняет изменённую PdfPage обратно в документ.

Рендеринг

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

Рендерит страницу в байты PNG или JPEG с управлением DPI, фоном, прозрачностью, отрисовкой аннотаций, качеством JPEG и исключёнными слоями.

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

Рендерит страницу в сырой RGBA-объект RenderedPixmap (именованный кортеж с width, height, data).

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

Рендерит цветоделённые формы по каждому красителю для страницы. Возвращает список именованных кортежей SeparationPlate (name, width, height, data).

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

Рендерит одну именованную цветоделённую форму красителя.

Метод Тип возврата Описание
render_page_fit(page, fit_width, fit_height, format=0) bytes Рендерит страницу, масштабированную под пиксельную область
flatten_to_images(dpi=150) bytes Сводит все страницы в PDF на основе изображений

Сохранение

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

Сохраняет PDF в файл. Управляйте сжатием потоков, сборкой «мусора» (мёртвых объектов) и линеаризацией (быстрый веб-просмотр).

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

Сериализует PDF в байты с теми же опциями, что и у 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

Сохраняет с защитой паролем AES-256 и управлением разрешениями. Если owner_password равен None, используется пароль пользователя.

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

Сериализует зашифрованный AES-256 PDF в байты.

Page

Ленивый дескриптор страницы, возвращаемый doc[i] или итерацией по PdfDocument. Все свойства вычисляются при обращении и делегируются родительскому документу.

from pdf_oxide import PdfDocument

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

Свойства (ленивые)

Свойство Тип Описание
index int Индекс страницы с отсчётом от нуля
width, height float Размеры страницы в пунктах PDF
bbox tuple[float, 4] (llx, lly, urx, ury)
text str Извлечённый простой текст
chars, words, lines, spans list[...] Структурированный текст
tables list[dict] Таблицы со строками + ячейками (текст + bbox)
images, paths, annotations list[...] Содержимое страницы

Методы

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

Ленивый объект страницы также доступен как doc.pages() (итератор, эквивалентный прямой итерации по документу).

PdfPage

DOM-подобный дескриптор страницы для поэлементного доступа и редактирования. Получается через PdfDocument.page().

from pdf_oxide import PdfDocument

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

Свойства

Свойство Тип Описание
index int Индекс страницы с отсчётом от нуля
width float Ширина страницы в пунктах PDF
height float Высота страницы в пунктах PDF

Методы

page.children() -> list[PdfElement]

Получает все элементы на странице.

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

Находит все текстовые элементы, содержащие заданную подстроку.

page.find_images() -> list[PdfImage]

Находит все элементы-изображения на странице.

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

Получает конкретный элемент по его ID.

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

Заменяет текстовое содержимое элемента, идентифицируемого его PdfTextId.

page.annotations() -> list[PdfAnnotation]

Получает все аннотации на странице.

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

Добавляет аннотацию-ссылку URL. Возвращает ID аннотации.

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

Добавляет аннотацию-выделение с цветом RGB. Возвращает ID аннотации.

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

Добавляет аннотацию-стикер. Возвращает ID аннотации.

page.remove_annotation(index: int) -> bool

Удаляет аннотацию по индексу. Возвращает True, если удаление выполнено.

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

Добавляет новый текст на страницу. Возвращает PdfTextId для последующего обращения.

page.remove_element(element_id: PdfTextId) -> bool

Удаляет элемент по его ID. Возвращает True, если удаление выполнено.

Пример

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

Единый класс для создания PDF из различных исходных форматов.

from pdf_oxide import Pdf

Фабричные методы

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

Создаёт PDF из содержимого Markdown.

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

Создаёт PDF из содержимого HTML.

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

Создаёт PDF из простого текста.

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

Создаёт PDF из Markdown, отрисованного через именованный CSS/шаблон компоновки.

Pdf.from_image(path: str) -> Pdf

Создаёт одностраничный PDF из файла изображения (JPEG, PNG).

Pdf.from_bytes(data: bytes) -> Pdf

Открывает существующий PDF из байтов в памяти для изменения. Удобно при загрузке PDF из S3, HTTP или баз данных.

from pdf_oxide import Pdf

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

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

Создаёт многостраничный PDF из нескольких файлов изображений — по одной странице на изображение.

Pdf.from_image_bytes(data: bytes) -> Pdf

Создаёт одностраничный PDF из байтов изображения.

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

Объединяет несколько PDF-файлов (по пути) в один Pdf.

Методы

pdf.save(path: str) -> None

Сохраняет PDF в файл.

pdf.to_bytes() -> bytes

Возвращает содержимое PDF в виде байтов.

len(pdf) -> int

Возвращает размер PDF в байтах (через __len__).

PdfText

Представляет текстовый элемент на странице. Возвращается методом PdfPage.find_text_containing().

Свойство Тип Описание
id PdfTextId Уникальный идентификатор элемента
value str Текстовое содержимое
text str Текстовое содержимое (псевдоним value)
bbox tuple[float, float, float, float] Ограничивающий прямоугольник (x0, y0, x1, y1)
font_name str Имя шрифта в PostScript
font_size float Размер шрифта в пунктах
is_bold bool Является ли текст полужирным
is_italic bool Является ли текст курсивным

Методы

Метод Параметры Возвращает Описание
contains(needle) str bool Проверить, содержит ли текст подстроку
starts_with(prefix) str bool Проверить, начинается ли текст с префикса
ends_with(suffix) str bool Проверить, заканчивается ли текст суффиксом

PdfImage

Представляет элемент-изображение на странице. Возвращается методом PdfPage.find_images().

Свойство Тип Описание
bbox tuple[float, float, float, float] Ограничивающий прямоугольник (x0, y0, x1, y1)
width int Ширина изображения в пикселях
height int Высота изображения в пикселях
aspect_ratio float Соотношение ширины к высоте

PdfAnnotation

Представляет аннотацию на странице. Возвращается методом PdfPage.annotations().

Свойство Тип Описание
subtype str Тип аннотации (например, "Link", "Highlight", "Text")
rect tuple[float, float, float, float] Позиция (x0, y0, x1, y1)
contents `str None`
color `tuple[float, float, float] None`
is_modified bool Была ли аннотация изменена
is_new bool Является ли аннотация только что добавленной

PdfElement

Универсальная обёртка элемента. Возвращается методом PdfPage.children().

Метод Возвращает Описание
is_text() bool Проверить, является ли элемент текстом
is_image() bool Проверить, является ли элемент изображением
is_path() bool Проверить, является ли элемент векторным контуром
is_table() bool Проверить, является ли элемент таблицей
is_structure() bool Проверить, является ли элемент элементом структуры
as_text() `PdfText None`
as_image() `PdfImage None`
Свойство Тип Описание
bbox tuple[float, float, float, float] Ограничивающий прямоугольник

TextChar

Представляет один символ с позиционированием и метаданными шрифта. Возвращается методом PdfDocument.extract_chars().

from pdf_oxide import TextChar  # or access via PdfDocument
Атрибут Тип Описание
char str Символ Юникода
bbox tuple[float, float, float, float] Ограничивающий прямоугольник (x0, y0, x1, y1)
font_name str Имя шрифта в PostScript
font_size float Размер шрифта в пунктах
font_weight str Насыщенность ("thin", "light", "normal", "medium", "semi-bold", "bold", "extra-bold", "black")
is_italic bool Является ли символ курсивным
color tuple[float, float, float] Цвет RGB (r, g, b), значения 0.0–1.0
rotation_degrees float Поворот символа в градусах
origin_x float Координата X начала текста
origin_y float Координата Y начала текста
advance_width float Ширина продвижения глифа
mcid `int None`

Пример

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

Представляет последовательность текста с одинаковым шрифтом и стилем. Возвращается методом PdfDocument.extract_spans().

Атрибут Тип Описание
text str Текстовое содержимое
bbox tuple[float, float, float, float] Ограничивающий прямоугольник (x0, y0, x1, y1)
font_name str Имя шрифта в PostScript
font_size float Размер шрифта в пунктах
is_bold bool Является ли спан полужирным
is_italic bool Является ли спан курсивным
is_monospace bool Является ли шрифт моноширинным (Courier, Consolas и т. д.)
char_widths list[float] Ширины продвижения по каждому глифу для точных ограничивающих прямоугольников
color tuple[float, float, float] Цвет RGB (r, g, b), значения 0.0–1.0

Пример

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}")

Извлечение изображений

extract_images() возвращает объекты ImageInfo с метаданными изображений. Для сырых данных изображений, пригодных для сохранения на диск, используйте extract_image_bytes().

Формат возврата extract_image_bytes()

Каждый словарь, возвращаемый extract_image_bytes(), имеет следующие ключи:

Ключ Тип Описание
width int Ширина изображения в пикселях
height int Высота изображения в пикселях
data bytes Сырые данные изображения
format str Формат изображения (например, "png", "jpeg")

Пример

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

Представляет совпадение текстового поиска. Возвращается методами search() и search_page().

Атрибут Тип Описание
page int Индекс страницы с отсчётом от нуля
text str Найденный текст
x float Координата X в пунктах PDF
y float Координата Y в пунктах PDF

FormField

Представляет поле формы. Возвращается методом PdfDocument.get_form_fields().

Свойство Тип Описание
name str Полностью квалифицированное имя поля
field_type str Тип поля: "text", "button", "choice", "signature" или "unknown"
value `str bool
tooltip `str None`
bounds `tuple[float, float, float, float] None`
flags `int None`
max_length `int None`
is_readonly bool Является ли поле доступным только для чтения
is_required bool Является ли поле обязательным

TextWord

Последовательность текста, сгруппированная по словам. Возвращается методами PdfDocument.extract_words() и PdfPageRegion.extract_words().

Свойство Тип Описание
text str Текст слова
bbox tuple[float, float, float, float] Ограничивающий прямоугольник (x0, y0, x1, y1)
font_name str Имя шрифта в PostScript
font_size float Размер шрифта в пунктах
is_bold bool Является ли слово полужирным
is_italic bool Является ли слово курсивным
chars list[TextChar] Составляющие символы

TextLine

Последовательность текста, сгруппированная по строкам. Возвращается методами PdfDocument.extract_text_lines() и PdfPageRegion.extract_text_lines().

Свойство Тип Описание
text str Текст строки
bbox tuple[float, float, float, float] Ограничивающий прямоугольник (x0, y0, x1, y1)
words list[TextWord] Слова в строке
chars list[TextChar] Символы в строке

PdfPageRegion

Обрезанная область страницы. Возвращается методами PdfDocument.within() и PdfPage.region().

Свойство Тип Описание
bbox tuple[float, float, float, float] Границы области

Методы

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

Методы извлечения, ограниченные ограничивающим прямоугольником области.

LayoutParams

Вычисленные адаптивные параметры компоновки страницы. Возвращается методом PdfDocument.page_layout_params().

Свойство Тип Описание
word_gap_threshold float Порог межсловного интервала в пунктах
line_gap_threshold float Порог межстрочного интервала в пунктах
median_char_width float Медианная ширина символа
median_font_size float Медианный размер шрифта
median_line_spacing float Медианный межстрочный интервал
column_count int Обнаруженное количество текстовых колонок

ExtractionProfile

Настраиваемый профиль извлечения текста, передаваемый в extract_words() / extract_text_lines().

from pdf_oxide import ExtractionProfile

Статические конструкторы

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

Свойства

Свойство Тип Описание
name str Имя профиля
tj_offset_threshold float Порог разрыва слов по смещению в массиве TJ
word_margin_ratio float Коэффициент межсловного отступа
space_threshold_em_ratio float Порог ширины пробела (коэффициент em)
space_char_multiplier float Множитель символа пробела
use_adaptive_threshold bool Включены ли адаптивные пороги

OfficeConverter

Преобразует документы Office (DOCX, XLSX, PPTX) в PDF. Требует функции office в сборке Rust.

from pdf_oxide import OfficeConverter

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

Методы

OfficeConverter.from_docx(path: str) -> Pdf

Преобразует документ Word в объект Pdf.

OfficeConverter.from_docx_bytes(data: bytes) -> Pdf

Преобразует байты документа Word в объект Pdf.

OfficeConverter.from_xlsx(path: str) -> Pdf

Преобразует таблицу Excel в объект Pdf.

OfficeConverter.from_xlsx_bytes(data: bytes) -> Pdf

Преобразует байты таблицы Excel в объект Pdf.

OfficeConverter.from_pptx(path: str) -> Pdf

Преобразует презентацию PowerPoint в объект Pdf.

OfficeConverter.from_pptx_bytes(data: bytes) -> Pdf

Преобразует байты презентации PowerPoint в объект Pdf.

OfficeConverter.convert(path: str) -> Pdf

Автоматически определяет формат и преобразует любой поддерживаемый документ Office в объект Pdf.

Пример

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

Классы графики

Эти классы доступны для продвинутого создания PDF с графикой:

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

Градиенты

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

Требуют функции ocr в сборке Rust.

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) построитель для постраничной компоновки PDF. См. пример ниже и Создание с нуля.

from pdf_oxide import DocumentBuilder

Методы уровня документа

Метод Параметры Описание
DocumentBuilder() – Создать новый построитель
title(title) str Задать заголовок документа
author(author) str Задать автора документа
subject(subject) str Задать тему документа
keywords(keywords) str Задать ключевые слова документа
creator(creator) str Задать имя приложения-создателя
on_open(script) str Задать JavaScript-действие при открытии на уровне документа
tagged_pdf_ua1() – Создать доступный тегированный документ PDF/UA-1
language(lang) str Задать язык документа (например, "en-US")
role_map(custom, standard) str, str Сопоставить пользовательский структурный тег со стандартным
register_embedded_font(name, font) str, EmbeddedFont Зарегистрировать шрифт (потребляет EmbeddedFont)

Фабрики страниц

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

Вывод

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

Буферизует операции уровня страницы до вызова done(). Возвращается методами DocumentBuilder.a4_page() / letter_page() / page(). Каждый метод возвращает self для цепочечного вызова; done() фиксирует страницу и возвращает родительский DocumentBuilder.

Текст и компоновка

Метод Параметры Описание
font(name, size) str, float Задать текущий шрифт и размер
at(x, y) float, float Переместить курсор в абсолютную позицию
text(text) str Нарисовать текст в позиции курсора
heading(level, text) int, str Нарисовать заголовок (уровень 1–6)
paragraph(text) str Нарисовать абзац с переносом строк
space(points) float Сместиться по вертикали
horizontal_rule() – Нарисовать горизонтальный разделитель
columns(column_count, gap_pt, text) int, float, str Сбалансированный многоколоночный поток текста
footnote(ref_mark, note_text) str, str Встроенный знак сноски + примечание внизу страницы
new_page_same_size() – Начать новую страницу с теми же размерами
measure(text) -> float str Измерить ширину отрисованного текста в пунктах
remaining_space() -> float – Оставшееся вертикальное пространство на странице

Встроенные фрагменты

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)

Аннотации разметки

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

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)

Графика

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)

Изображения и штрихкоды

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.

Таблицы

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

Фиксация

page.done() -> DocumentBuilder

EmbeddedFont

Шрифт TTF/OTF, зарегистрированный в DocumentBuilder.

from pdf_oxide import EmbeddedFont

EmbeddedFont.from_file(path: str) -> EmbeddedFont
EmbeddedFont.from_bytes(data: bytes, name: str | None = None) -> EmbeddedFont
Свойство Тип Описание
name str Зарегистрированное имя шрифта

Таблицы

Объекты-значения для текучего табличного 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)
Свойство Тип Описание
header str Текст заголовка колонки
width float Ширина колонки в пунктах
align int Выравнивание ячеек

Table

from pdf_oxide import Table

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

Буферизованная таблица, потребляемая методом FluentPageBuilder.table(). При has_header=True заголовки колонок отрисовываются как стилизованная строка-заголовок.

StreamingTable

Дескриптор таблицы с потоковой подачей строк, возвращаемый методом FluentPageBuilder.streaming_table(), для таблиц, слишком больших для одномоментной материализации.

Метод Параметры Описание
push_row(cells) list[str] Добавить строку из строковых ячеек
push_row_span(cells) list[tuple[str, int]] Добавить строку из ячеек (text, colspan)
flush() – Сбросить текущий пакет
finish() – Завершить таблицу, возвращая FluentPageBuilder
column_count() – → int Количество колонок
pending_row_count() – → int Строки в буфере, ещё не зафиксированные
batch_count() – → int Количество завершённых пакетов

Шаблоны страниц

Повторяющиеся артефакты колонтитулов, применяемые ко всем страницам.

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

Цифровые подписи

Подписывайте, проставляйте метки времени и проверяйте PDF (PAdES / LTV). Требует функции signatures (и опционально tsa-client) в сборке Rust.

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
Метод Возвращает Описание
subject() str DN субъекта сертификата
issuer() str DN издателя сертификата
serial() str Серийный номер
validity() tuple[int, int] Метки времени Unix (not_before, not_after)
is_valid() bool Находится ли сертификат сейчас в пределах срока действия

Signature

Возвращается методом PdfDocument.signatures().

Свойство / метод Тип Описание
signer_name `str None`
reason `str None`
location `str None`
contact_info `str None`
signing_time `int None`
covers_whole_document bool Покрывает ли подпись весь файл
pades_level PadesLevel Обнаруженный базовый уровень PAdES (B-B/B-T/B-LT)
verify() bool Криптографически проверить подпись
verify_detached(pdf_data) bool Проверка, включая messageDigest, против байтов файла

Timestamp

from pdf_oxide import Timestamp

Timestamp.parse(data: bytes) -> Timestamp
Свойство / метод Тип Описание
time int Время метки (Unix)
serial str Серийный номер ответа TSA
policy_oid str OID политики TSA
tsa_name str Имя TSA
hash_algorithm int Код алгоритма хеширования отпечатка сообщения
message_imprint bytes Хешированный отпечаток сообщения
verify() bool Проверить токен метки времени

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
)

Сертификаты, CRL и ответы OCSP в кодировке DER для подписания на уровне B-LT.

Dss

Разобранный Document Security Store, возвращаемый методом PdfDocument.dss().

Свойство Тип Описание
certs list[bytes] DER-блобы сертификатов уровня документа
crls list[bytes] DER-блобы CRL
ocsps list[bytes] DER-блобы ответов OCSP
vri list[str] Ключи VRI по каждой подписи (hex SHA-1 от /Contents)

Функции уровня модуля

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

Подписание

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

Подписывает сырые байты PDF загруженным сертификатом Certificate для подписания и возвращает подписанный PDF.

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

Подписывает сырые байты PDF на базовом уровне PAdES. B_T/B_LT требуют tsa_url.

has_document_timestamp(pdf_data: bytes) -> bool

Несёт ли PDF архивную метку времени RFC 3161 на уровне документа (PAdES-B-LTA).

Штрихкоды

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

Генерирует одномерный штрихкод или QR-код в виде строки SVG. Требует функции barcodes.

Разбиение по закладкам

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]]

Планирует или выполняет разбиение PDF по границам закладок. plan_* возвращает только метаданные сегментов; split_* возвращает каждый сегмент в паре с его байтами PDF.

Подготовка моделей OCR

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

Подготавливает модели OCR для офлайн/изолированного использования, инспектирует манифест моделей (JSON) и проверяет, может ли эта сборка загружать модели.

Логирование

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

Настройка движка

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

Регулирует ограничение на число операторов в потоке (защита от вредоносного ввода) и сохранение U+FFFD для несопоставленных глифов. Оба метода возвращают предыдущее значение.

Криптографическое управление

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)

Асинхронный API

Обёртки async/await, которые выполняют блокирующие операции в пуле потоков. Методы зеркалируют свои синхронные аналоги.

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()
Класс Конструкторы Примечания
AsyncPdfDocument await AsyncPdfDocument.open(path, password=None), await AsyncPdfDocument.from_bytes(data, password=None) Все методы PdfDocument доступны как awaitable; поддерживает async with и .close()
AsyncPdf оборачивает фабричные методы Pdf await pdf.save(path), await pdf.to_bytes()
AsyncOfficeConverter оборачивает статические методы OfficeConverter например, await AsyncOfficeConverter.from_docx(path)

Обработка ошибок

PdfError

Все ошибки, характерные для PDF, выбрасывают PdfError:

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

Типичные сценарии ошибок:

Исключение Причина
PdfError Повреждённый PDF, зашифрован без пароля, сбой разбора
FileNotFoundError Файл не существует
IndexError Индекс страницы превышает page_count()
ValueError Некорректный аргумент (например, отрицательный индекс страницы)

Полный пример

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})")

Добавления в 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

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

См. Создание из HTML.

Проверка подписей

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)

Подробности см. в разделе Цифровые подписи.

Рендеринг

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. Координаты в пунктах PDF от нижнего левого угла.

Сведение Pdf

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

Other Language Bindings

PDF Oxide предоставляет нативные привязки для всех основных экосистем: Rust, Node.js, WASM, C#, Golang, Java, PHP, Ruby, C++, Swift, Kotlin, Dart, R, Julia, Zig, Scala, Clojure, Objective-C, и Elixir.

Дальнейшие шаги