postext for Python

Typeset books from Python with Postext: a print-ready PDF, HTML pages, an EPUB, page images or a Word document from a .postext book, a book folder or loose Markdown files.

pip install postext

import postext

report = postext.pdf("book.postext", out="book.pdf", set={"page.dpi": 300})
print(report.output.pages, "pages")
for warning in report.warnings:
    print(warning)            # warning missingFont (chapters/02.md:14): …

pdf = postext.pdf_bytes(open("book.postext", "rb").read())   # bytes in, bytes out

The package drives the self-contained postext command line, the same executable as brew install drnachio/postext/postext or npx postext-cli: the layout is the Sandbox's, and the same book breaks into the same pages. The wheel is pure Python with no dependencies. The executable of your system (185 to 230 MB, too large for a wheel) is downloaded on first use from the GitHub Release of the package's version, checked against the release's SHA256SUMS and kept in the cache:

python -m postext pdf book.postext -o book.pdf runs the command line itself.

Commands

Every command of the command line is a function. Each runs the command with --json and returns its report.

book is a path (a .postext file, a book folder, a Markdown file), a list of Markdown files (the chapters, in order), or the bytes of a .postext bundle. The commands that read a book take the book options:

postext.pdf(
    ["01.md", "02.md"],
    out="notes.pdf",
    name="Notes",                      # --name
    config={"page": {"sizePreset": "A5"}},   # --config (a dict or a file)
    set={"bodyText.fontSize.value": 11},     # --set, one per key
    locale="es",                       # --locale
    chapters=range(1, 3),              # --chapters 1-2 (also 3, "1,3-5", [1, 3])
    resources="img/", fonts="fonts/",  # --resources, --fonts
    font_dirs=["~/Fonts"],             # --font-dir
    offline=True,                      # --offline: never download fonts
)

Reports and warnings

A Report has ok, command, version, exit_code, pages, book (name, id, locale, chapters), outputs (Output: kind, path, size, pages), warnings (Diagnostic: kind, message, severity, at, page, data), timings and raw, the whole JSON object. InfoReport adds chapters, resources and fonts; CheckReport adds passed, error_count, warning_count, contrast, reflow and preflight.

Bytes out

out="-" (or postext.STDOUT) writes to stdout and returns the bytes in report.content; pdf_bytes, html_bytes, epub_bytes, image_bytes, docx_bytes and pack_bytes return them directly. A book given as bytes with no out comes back as bytes.

Errors

One executable, many runs

postext.Postext(binary=None, cwd=None, env=None, timeout=None, offline=None, font_dirs=None) has the same methods with its own executable, folder, environment and timeout. Postext().run(["build", "book/", "--pdf", "b.pdf", "--watch"], capture=False) runs any command as typed.

Each call starts the executable again. A mode that keeps one engine running between calls is planned.

Docs

• Command line: https://postext.dev/en/docs/command-line#python
• Source: https://github.com/drnachio/postext/tree/main/packages/postext-python

MIT licence.