postext 1.70.5__tar.gz

postext-1.70.5/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+build/
+dist/

postext-1.70.5/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Postext contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

postext-1.70.5/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: postext
+Version: 1.70.5
+Summary: Typeset books from Python with Postext: PDF, HTML, EPUB, page images and Word from a .postext book or Markdown, through the self-contained postext command line.
+Project-URL: Homepage, https://postext.dev/
+Project-URL: Documentation, https://postext.dev/en/docs/command-line#python
+Project-URL: Source, https://github.com/drnachio/postext/tree/main/packages/postext-python
+Project-URL: Issues, https://github.com/drnachio/postext/issues
+Author: Postext contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: book,epub,layout,markdown,pdf,postext,typesetting
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Printing
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# postext for Python
+
+Typeset books from Python with [Postext](https://postext.dev/): 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.
+
+```bash
+pip install postext
+```
+
+```python
+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:
+
+| System | Executable |
+| --- | --- |
+| macOS, Apple silicon / Intel | `postext-macos-arm64` / `postext-macos-x64` |
+| Linux x86-64 / ARM64 (glibc) | `postext-linux-x64` / `postext-linux-arm64` |
+| Linux x86-64, musl (Alpine) | `postext-linux-x64-musl` |
+| Windows x64 (and ARM, emulated) | `postext-windows-x64.exe` |
+
+| Environment variable | Effect |
+| --- | --- |
+| `POSTEXT_BIN` | Run this executable instead (Homebrew, Scoop, a local build); nothing is downloaded |
+| `POSTEXT_CACHE_DIR` | Cache folder (default `~/.cache/postext`, `%LOCALAPPDATA%\postext\cache` on Windows); executables go in `bin/<version>/`, downloaded fonts in `fonts/` |
+| `POSTEXT_RELEASE_URL` | Download from a mirror: a URL with `{version}` where the release's files are |
+
+`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.
+
+| Function | Command | Returns |
+| --- | --- | --- |
+| `pdf(book, out=…, pdfx=…, profile=…, color_space=…)` | `postext pdf` | `Report` |
+| `html(book, out=…, mode=…, assets=…)` | `postext html` | `Report` |
+| `epub(book, out=…, layout=…, cover=…)` | `postext epub` | `Report` |
+| `image(book, page="#1", out=…, dpi=…, format=…)` | `postext image` | `ImageReport` |
+| `images(book, out="pages/", pages=…, pattern=…)` | `postext images` | `Report` |
+| `docx(book, out=…, variant=…)` | `postext docx` | `Report` |
+| `import_docx(docx, book=None, out=…, dry_run=…)` | `postext import-docx` | `ImportDocxReport` |
+| `pack(book, out=…)` / `unpack(bundle, out=…)` | `postext pack` / `unpack` | `Report` / `UnpackReport` |
+| `info(book, pages=True)` | `postext info` | `InfoReport` |
+| `check(book, strict=True)` | `postext check` | `CheckReport` |
+| `build(book, pdf=…, html=…, epub=…, images=…, docx=…)` | `postext build` | `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:
+
+```python
+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
+
+| Exception | When |
+| --- | --- |
+| `PostextError` | The command failed (exit code 1); `err.report` and `err.stderr` say why |
+| `UsageError` | A wrong option or value (exit code 2) |
+| `ProblemsFound` | `check` found an error (any warning with `strict`), or `import_docx` could not apply an edit (exit code 3); `raise_on_problems=False` returns the report instead |
+| `BinaryNotFound` | No executable for this system, a failed download or checksum, or a `POSTEXT_BIN` that is not a file |
+
+### 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.

postext-1.70.5/README.md

@@ -0,0 +1,124 @@
+# postext for Python
+
+Typeset books from Python with [Postext](https://postext.dev/): 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.
+
+```bash
+pip install postext
+```
+
+```python
+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:
+
+| System | Executable |
+| --- | --- |
+| macOS, Apple silicon / Intel | `postext-macos-arm64` / `postext-macos-x64` |
+| Linux x86-64 / ARM64 (glibc) | `postext-linux-x64` / `postext-linux-arm64` |
+| Linux x86-64, musl (Alpine) | `postext-linux-x64-musl` |
+| Windows x64 (and ARM, emulated) | `postext-windows-x64.exe` |
+
+| Environment variable | Effect |
+| --- | --- |
+| `POSTEXT_BIN` | Run this executable instead (Homebrew, Scoop, a local build); nothing is downloaded |
+| `POSTEXT_CACHE_DIR` | Cache folder (default `~/.cache/postext`, `%LOCALAPPDATA%\postext\cache` on Windows); executables go in `bin/<version>/`, downloaded fonts in `fonts/` |
+| `POSTEXT_RELEASE_URL` | Download from a mirror: a URL with `{version}` where the release's files are |
+
+`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.
+
+| Function | Command | Returns |
+| --- | --- | --- |
+| `pdf(book, out=…, pdfx=…, profile=…, color_space=…)` | `postext pdf` | `Report` |
+| `html(book, out=…, mode=…, assets=…)` | `postext html` | `Report` |
+| `epub(book, out=…, layout=…, cover=…)` | `postext epub` | `Report` |
+| `image(book, page="#1", out=…, dpi=…, format=…)` | `postext image` | `ImageReport` |
+| `images(book, out="pages/", pages=…, pattern=…)` | `postext images` | `Report` |
+| `docx(book, out=…, variant=…)` | `postext docx` | `Report` |
+| `import_docx(docx, book=None, out=…, dry_run=…)` | `postext import-docx` | `ImportDocxReport` |
+| `pack(book, out=…)` / `unpack(bundle, out=…)` | `postext pack` / `unpack` | `Report` / `UnpackReport` |
+| `info(book, pages=True)` | `postext info` | `InfoReport` |
+| `check(book, strict=True)` | `postext check` | `CheckReport` |
+| `build(book, pdf=…, html=…, epub=…, images=…, docx=…)` | `postext build` | `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:
+
+```python
+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
+
+| Exception | When |
+| --- | --- |
+| `PostextError` | The command failed (exit code 1); `err.report` and `err.stderr` say why |
+| `UsageError` | A wrong option or value (exit code 2) |
+| `ProblemsFound` | `check` found an error (any warning with `strict`), or `import_docx` could not apply an edit (exit code 3); `raise_on_problems=False` returns the report instead |
+| `BinaryNotFound` | No executable for this system, a failed download or checksum, or a `POSTEXT_BIN` that is not a file |
+
+### 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.

postext-1.70.5/pyproject.toml

@@ -0,0 +1,55 @@
+[build-system]
+requires = ["hatchling>=1.26"]
+build-backend = "hatchling.build"
+
+[project]
+name = "postext"
+dynamic = ["version"]
+description = "Typeset books from Python with Postext: PDF, HTML, EPUB, page images and Word from a .postext book or Markdown, through the self-contained postext command line."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Postext contributors" }]
+keywords = ["postext", "typesetting", "pdf", "epub", "markdown", "book", "layout"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Operating System :: POSIX :: Linux",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Printing",
+    "Topic :: Text Processing :: Markup :: Markdown",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest>=7"]
+
+[project.urls]
+Homepage = "https://postext.dev/"
+Documentation = "https://postext.dev/en/docs/command-line#python"
+Source = "https://github.com/drnachio/postext/tree/main/packages/postext-python"
+Issues = "https://github.com/drnachio/postext/issues"
+
+[tool.hatch.version]
+path = "src/postext/_version.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/postext"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/postext", "tests", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 140
+target-version = "py39"
+
+[tool.ruff.lint]
+select = ["F", "E9", "B"]

postext-1.70.5/src/postext/__init__.py

@@ -0,0 +1,123 @@
+"""Postext from Python.
+
+Typesets books with the self-contained ``postext`` command line: PDF, HTML,
+EPUB, page images and Word from a ``.postext`` book, a book folder or loose
+Markdown. The executable of this system is downloaded from the GitHub
+Release of this package's version on first use, checked against its SHA256
+and cached; ``POSTEXT_BIN`` points at one already installed.
+
+    import postext
+
+    report = postext.pdf("book.postext", out="book.pdf", set={"page.dpi": 300})
+    print(report.output.pages, [str(w) for w in report.warnings])
+
+    pdf = postext.pdf_bytes(open("book.postext", "rb").read())
+
+Every function runs the command with ``--json`` and returns its report
+(:class:`Report` and kin). A failure raises :class:`PostextError`
+(:class:`UsageError` for a wrong call, :class:`ProblemsFound` when ``check``
+finds problems). :class:`Postext` runs a given executable, in a given folder
+or with a timeout.
+"""
+
+from ._binary import cache_dir, cached_binary, download_binary, find_binary, platform_file
+from ._client import STDOUT, BookInput, Books, Postext
+from ._errors import BinaryNotFound, PostextError, ProblemsFound, UsageError
+from ._report import (
+    BookSummary,
+    ChapterInfo,
+    CheckReport,
+    Diagnostic,
+    FontInfo,
+    ImageReport,
+    ImportDocxReport,
+    InfoReport,
+    Output,
+    PageRef,
+    Report,
+    UnpackReport,
+)
+from ._version import __version__
+
+_default = Postext()
+
+pdf = _default.pdf
+html = _default.html
+epub = _default.epub
+image = _default.image
+images = _default.images
+docx = _default.docx
+import_docx = _default.import_docx
+pack = _default.pack
+unpack = _default.unpack
+info = _default.info
+check = _default.check
+build = _default.build
+
+pdf_bytes = _default.pdf_bytes
+html_bytes = _default.html_bytes
+epub_bytes = _default.epub_bytes
+image_bytes = _default.image_bytes
+docx_bytes = _default.docx_bytes
+pack_bytes = _default.pack_bytes
+
+run = _default.run
+
+
+def binary() -> str:
+    """The path of the executable the functions run (downloaded on first call)."""
+    return str(find_binary())
+
+
+__all__ = [
+    "__version__",
+    "Postext",
+    "STDOUT",
+    "BookInput",
+    "Books",
+    # commands
+    "pdf",
+    "html",
+    "epub",
+    "image",
+    "images",
+    "docx",
+    "import_docx",
+    "pack",
+    "unpack",
+    "info",
+    "check",
+    "build",
+    "pdf_bytes",
+    "html_bytes",
+    "epub_bytes",
+    "image_bytes",
+    "docx_bytes",
+    "pack_bytes",
+    "run",
+    # executable
+    "binary",
+    "find_binary",
+    "download_binary",
+    "platform_file",
+    "cache_dir",
+    "cached_binary",
+    # reports
+    "Report",
+    "InfoReport",
+    "CheckReport",
+    "ImageReport",
+    "ImportDocxReport",
+    "UnpackReport",
+    "Output",
+    "Diagnostic",
+    "BookSummary",
+    "ChapterInfo",
+    "FontInfo",
+    "PageRef",
+    # errors
+    "PostextError",
+    "UsageError",
+    "ProblemsFound",
+    "BinaryNotFound",
+]

postext-1.70.5/src/postext/__main__.py

@@ -0,0 +1,8 @@
+"""``python -m postext pdf book.postext -o book.pdf``: the command line itself,
+downloaded on first use like the functions'."""
+
+import sys
+
+from ._client import _main
+
+sys.exit(_main())