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;flagleaves the text and attaches findings;discardwithholds all content if anything reaches the threshold.threshold:low,medium(default) orhigh.excerpts: include the offending text in each finding. For a human audit log only: an excerpt of an injection is one.limits: aLimits, or a dict of PHP's names ({"maxFileBytes": ...}).words: also give each pagewords.
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.