Skip to main content

fancy-fine-print

The Python port of particle-academy/fine-print's PDF reader: text in reading order, per-word boxes, and an agent-read guard against prompt injection, with every hostile-input guard of the PHP reference. Zero runtime dependencies: the standard library only, including our own RC4 and AES.

Status: 0.1.0, pre-1.0, reader only. There is no writer and no renderer yet; they follow. Pre-1.0, a minor release may change the API.

pip install fancy-fine-print
import fine_print

result = fine_print.read(pdf_bytes, words=True)
if result["ok"]:
    for page in result["pages"]:
        print(page["page"], page["width"], page["height"])
        print(page["text"])
        for w in page["words"]:          # {text, x0, x1, top, bottom}
            ...
else:
    print(result["refused"]["reason"])   # e.g. "decompression_bomb"

Python 3.11 or later. Install as fancy-fine-print, import as fine_print.

Parity with PHP

This package reproduces PHP fine-print 0.7.0's reader (fine_print.version() says so). Parity is a test result, not a claim: tests/test_parity_php.py runs PHP fine-print and this port over the same 801 PDFs, harvested from PHP's own test suite (every file PHP's tests open, with the limits they open it under), through six read variants, and requires the results to be equal: text, findings, notices, refusals and messages exactly, words and page geometry within 1e-6 pt. CI runs it on Linux and Windows against the PHP checkout pinned at v0.7.0, and a missing PHP fails the run.

The agent-facing texts are PHP's verbatim, including the redaction notice that names Agent::readUnredacted(); in Python that call is read_unredacted().

The agent surface

read(data, *, policy="redact", threshold="medium", excerpts=False, limits=None, words=False)

  • data: PDF bytes, or a path.
  • policy: redact (default) cuts instructions and hidden text at or above the threshold, replacing them with [fine-print: ...] markers and removing invisible characters; flag leaves the text and attaches findings; discard withholds all content if anything reaches the threshold.
  • threshold: low, medium (default) or high.
  • excerpts: include the offending text in each finding. For a human audit log only: an excerpt of an injection is one.
  • limits: a Limits, or a dict of PHP's names ({"maxFileBytes": ...}).
  • words: also give each page words.

The result: ok, version, pageCount, repaired, pages ({page, width, height, text, words?}), metadata, outline, annotations, activeContent, warnings, guard, redacted, unredacted, notice, encryption. A refused file returns {"ok": False, "refused": {"reason", "message"}}; bad options raise.

read_unredacted(data, *, threshold, excerpts, limits, words) is the deliberate second step: the same read, never redacted, with the findings attached. It takes no policy, so it cannot be turned back into a redacting read by accident; a host that must never show unredacted text does not expose it.

page_count(data, limits=None) raises RefusedException on a refused file.

Words

{text, x0, x1, top, bottom} per word, in reading order, in points on the DISPLAYED page: origin at the top-left of the crop box after /Rotate, x to the right, top and bottom measured down (top < bottom). A box runs from its first glyph's origin to its last glyph's advance, through the text matrix and the CTM, and from the font's descent to its ascent: the font descriptor's /Ascent and /Descent when sane (an ascent in (0, 2000], a descent in [-1000, 0]), else the standard-14 face the BaseFont names, else 0.8 / -0.2 em. A word whose box is not finite is dropped.

Every word is a substring of its page's text. Pieces of separate runs join only where the layout put them side by side with nothing between, never by geometry, and under redact a word touching an instruction or hidden text is dropped, and invisible characters are removed from inside a word, exactly as from the text.

The host surface

Document.open(data, limits=None) is the raw, unguarded view: pages(), page_text(n) ({text, spans, runs}), text(n), page_words(n), metadata(), xmp(), outline(), annotations(n), active_content(), encryption(), warnings(), repaired(). Hidden text is included and nothing is redacted: never hand it to an agent.

Guards

Every byte of a PDF is attacker-authored. Each limit refuses with a RefusedException whose reason is one of fine_print.REASONS, never a crash, a hang or a partial result:

limit (PHP name) default reason
maxFileBytes 256 MB too_large
maxObjects 1 000 000 too_many_objects
maxDepth 64 too_deep
maxStreamBytes 64 MB too_large
maxRatio above ratioFloorBytes 1500 above 1 MB decompression_bomb
maxTotalDecodedBytes 512 MB too_large
maxOperators 2 000 000 too_many_operators
maxFormDepth 12 (skipped, with a warning)
maxPages 50 000 too_many_pages
timeSeconds 30 time_budget
memoryBytes 256 MB memory_budget

Decompression is judged while it runs, in 4 KB chunks. Memory is accounted, not measured: the reader holds what it keeps alive at costs modelled on PHP's, so a read near memoryBytes may refuse at a slightly different point than PHP.

Encrypted files open with the empty user password only (RC4, AES-128, AES-256); anything needing a password is refused as encrypted. Nothing executes, follows or fetches: active content is reported by kind, location, length and SHA-256, never its body.

What is not here (yet)

  • The writer, the renderer and page serving (later phases).
  • Exchange (extract, export, portable content).
  • Unsupported in PHP's text path and therefore here: CFF/Type 3 glyph programs are never run, image codecs (DCT, JPX, CCITT, JBIG2) are kept as opaque bytes, vertical writing is read as horizontal, and multi-column pages read row by row across the columns.

License

MIT

Metadata

Release files for fancy-fine-print 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fancy-fine-print 0.1.0
File Size Uploaded Provenance Actions
fancy_fine_print-0.1.0.tar.gz 2.7 MB With provenance Details for fancy_fine_print-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fancy-fine-print 0.1.0
File Interpreter ABI Platform Actions
fancy_fine_print-0.1.0-py3-none-any.whl Python 3 none any Details for fancy_fine_print-0.1.0-py3-none-any.whl

Total release size: 2.7 MB

Release files / fancy_fine_print-0.1.0.tar.gz

Download URL fancy_fine_print-0.1.0.tar.gz
Size 2.7 MB
Tags Source
SHA-256 checksum
How to use checksums
f3d4aa8bd867e5eb4cdb9543bf84e2933839fa039ed6c0d86328e358805ee6de
BLAKE2b-256 checksum
How to use checksums
98da3a6a8879317d46b61d41d13324aa17f4b7fd365ebd5aee672da712cb96d8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Release files / fancy_fine_print-0.1.0-py3-none-any.whl

Download URL fancy_fine_print-0.1.0-py3-none-any.whl
Size 66.0 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d93afdc0002c86b1a75aae6aa278e4bbeccbb84e99bb5eb17141e662e52ecc51
BLAKE2b-256 checksum
How to use checksums
3dbd92fd04de4dd6e0275d7ff75236a9c2d9173db7546e5d48bccb4681a11cca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Security for fancy-fine-print 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for fancy_fine_print-0.1.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page