ozaru

Read PDF files from Python with a small, simple API and a Rust core.

Documentation: https://jair-dev57.github.io/ozaru/

import ozaru

text = ozaru.extract_text("invoice.pdf")
pages = ozaru.page_count("invoice.pdf")

print(f"{pages} pages")
print(text)

Why ozaru?

• One line per task. Pass a path and get the result. There are no objects to manage.
• Easy to install. Prebuilt wheels mean you don't need Rust or a compiler.
• No Python dependencies. ozaru installs nothing else into your environment.
• Built on Rust. The PDF work is done by pdf_oxide.
• Typed. Type hints are included, so your editor can autocomplete and check your calls.

Installation

pip install ozaru

Or, with uv:

uv add ozaru

ozaru requires Python 3.10 or newer.

Usage

Extract text

extract_text returns the text of the whole document as a single string:

import ozaru

text = ozaru.extract_text("report.pdf")

Count pages

page_count returns the number of pages as an integer:

import ozaru

pages = ozaru.page_count("report.pdf")

Handle errors

import ozaru

try:
    text = ozaru.extract_text("report.pdf")
except FileNotFoundError:
    print("The file does not exist.")
except OSError:
    print("The file could not be read.")
except ValueError:
    print("The file could not be read as a PDF.")

Damaged pages

If a page can't be read, extract_text still returns the other pages, leaves that page empty and emits an ozaru.PageWarning with its page number:

import warnings

import ozaru

with warnings.catch_warnings(record=True) as caught:
    warnings.simplefilter("always", ozaru.PageWarning)
    text = ozaru.extract_text("report.pdf")

for warning in caught:
    print(f"Page {warning.message.page} could not be read")

API

File problems raise the same OSError subclasses as Python's open(), such as FileNotFoundError, PermissionError and IsADirectoryError.

path can be a str or a pathlib.Path.

Supported platforms

Prebuilt wheels are available for CPython 3.10 and newer:

On other platforms, pip builds ozaru from source, which requires a Rust toolchain.

Limitations

ozaru is in early development, so its API may change between releases.

• It reads the text stored in a PDF and does not perform OCR, so scanned documents may return little or no text.
• It can't extract text from PDFs that need a password to open.

Contributing

You need Rust and uv. Then run:

git clone https://github.com/Jair-dev57/ozaru.git
cd ozaru
uv run pytest

See the contributing guide. Bug reports and ideas are welcome in the issue tracker.

License

ozaru is released under the MIT License.