open-document-skills AGENTS.md

AGENTS.md

Guidance for AI agents working on this repository. (Not to be confused with the skills/*/SKILL.md files — those instruct agents that use the skills; this file is for developing the repo.)

open-document-skills is a stdlib-only Python toolkit for OpenDocument files. odf_lib/ is the shared library, published to PyPI as open-document-lib; skills/{odt,odp,ods,odg}/ are the four agent skills.

Commands

# Tests — unittest, not pytest by default
python3 -m unittest discover -s tests

# Lint — BOTH are CI gates; ruff format is separate from ruff check
ruff check .
ruff format --check .

# Type-check — per directory: the four skills share module basenames
# (validate_refs.py etc.) and are not packages, so one combined run clashes
mypy odf_lib
for d in odt odp ods odg; do mypy skills/$d/scripts; done

# Build the library wheel
python3 -m build

The full suite needs the optional deps bibtexparser, lxml, hypothesis (pip install -e .[dev,scholarly,validate]). LibreOffice/Pandoc are optional — those tests skip when absent.

Conventions — do not break these

• Stdlib-only core. odf_lib/ and the skill scripts import nothing beyond the standard library. Optional deps (bibtexparser, lxml, pandoc) are lazily imported behind a clear error message.
• Shared helpers live in odf_lib/odf_common.py; each skill has a thin *_common.py wrapper. Skill scripts locate odf_lib via an upward search — never hardcode parents[N] depths.
• Every edit script calls update_meta_for_edit before writing output.
• Text replacement preserves inline children (text:span, text:note, text:bookmark, …) — use replace_text_in_element, never clear_children on a paragraph.
• mimetype is the first ZIP entry, stored uncompressed.
• JSON-builder / validation result dicts are typed dict[str, Any].
• New code must pass ruff check, ruff format --check, and mypy.

Generated — do not hand-edit

• examples/output/, dist/, build/ — build artifacts, gitignored.
• tests/fixtures/corpus/ — regenerated by tests/fixtures/corpus/build_corpus.py (needs LibreOffice).