feat(python): integrate pyodr bindings from OpenDocument.py

[andiwand]

🤖 Generated with Claude Code

Integrates the Python bindings from OpenDocument.py into the main repo as a new root python/ folder, so the old repo can be archived.

Bindings

The old bindings targeted odrcore 4.1.1, so they were rewritten from scratch against the current public API (public headers only, no internals):

• odr.hpp free functions: open (all overloads), list_file_types, mimetype, type/category/engine mappings, version info
• the full DecodedFile family incl. FontFile, DecoderEngine, DecodePreference, encryption/decrypt
• Document + complete typed element tree with Python iteration; everything returning an Element carries py::keep_alive so handles keep the originating Document alive
• all style structs, Measure/DynamicUnit, Color, PageLayout
• the HtmlService/HtmlView/bring_offline pipeline incl. HtmlConfig (all fields, resource_locator callables work), HtmlResource. Views returned by list_views pin their service Python object, so translate(...).list_views()[0] cannot dangle
• Filesystem/FileWalker/Archive, GlobalParams, typed exceptions (FileNotFound maps to Python's FileNotFoundError)
• HttpServer, gated by the central ODR_WITH_HTTP_SERVER option; listen/stop release the GIL. pyodr.has_http_server reports availability

The pyodr package ships a CLI: pyodr <file> renders and opens a document, pyodr <file> --serve hosts it over HTTP.

Build integration

• CMake: new ODR_PYTHON option (default OFF) includes python/CMakeLists.txt, which also configures standalone against an installed odrcore. Install of the CLI targets is now conditional on ODR_CLI (was unconditional and broke ODR_CLI=OFF builds).
• Conan: new with_python option (default False) requires pybind11/2.13.6 and wires ODR_PYTHON through the toolchain.
• Packaging: root pyproject.toml (scikit-build-core); wheels bundle the odr.js/css assets under pyodr/data and pyodr auto-configures GlobalParams on import (env var ODR_CORE_DATA_PATH also honored).

Tests

Hermetic pytest suite (32 tests) — inputs generated inline (txt/csv/json, a zip-built minimal ODT): detection/open, text extraction, document element walk + navigation, HTML translation via bring_offline, view lifetime, and a live HTTP server round-trip. Also registered as a CTest test (pyodr_pytest) when ODR_TEST is on.

CI (migrated from OpenDocument.py's format/pip/wheels workflows)

.github/workflows/python.yml:

• format: black --check python
• build-test: conan build with with_python=True + pytest on ubuntu-24.04/macos-26, reusing the existing conan profiles and caches
• wheels: per-OS wheel builds, smoke-tested by installing the wheel and re-running pytest; wheels build without pdf2htmlEX/wvWare/libmagic since their runtime data cannot ship inside a wheel
• sdist + publish: releases attach the wheels and sdist as GitHub release assets. Nothing goes to PyPI yet — pip cannot build the sdist in an isolated backend (the build needs the conan-generated toolchain plus the conan-odr-index recipes, which the sdist excludes), and the Linux wheels are not manylinux-audited. PyPI publishing via cibuildwheel+conan is a follow-up.

Core fix

TextFile::text() was an unimplemented stub (return ""; // TODO) — now reads the underlying stream.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: badb623522

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".