Довідник 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. Опис Node.js API дивіться в Довіднику Node.js API, а опис WASM API — у Довіднику WASM API. Деталі щодо типів дивіться в розділі Типи та enum.

---

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) або фарби/сепарації (ink/separation) за іменем, а також увімкнути чи вимкнути реконструкцію таблиць.

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]

Видобуває текстові спани з метаданими шрифту. Кожен спан — це послідовність тексту з однаковим стилем. Передайте reading_order="column_aware" для багатоколонкових PDF.

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]

Видобуває всі зображення зі сторінки, включно із зображеннями в content stream і вкладених 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	–	Зняти позначку зведення зі сторінки

Редагування (Redaction)

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.

Page 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	Символ Unicode
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()	–	Створити доступний документ Tagged 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	–	Залишок вертикального простору на сторінці

Вбудовані фрагменти (inline runs)

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	Зареєстрована назва шрифту

---

Таблиці

Об’єкти-значення для плавного (fluent) 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()

Header / Footer

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

Генерує 1D-штрихкод або 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 flatten

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.

Наступні кроки

• Типи та переліки — усі спільні типи та переліки
• Довідник API сторінки — узгоджена ітерація по сторінках для всіх прив’язок
• Початок роботи з Python — посібник