This file provides guidance to AI coding agents working with code in this repository.
The project uses uv (Python >=3.10; CI tests 3.10–3.14).
uv sync # install deps (dev group)
uv run pytest . --doctest-modules --doctest-glob "README.md" # full suite, as CI runs it
uv run pytest tests/unit_test.py::FrontmatterTest::test_name # single test (unittest classes)
uv run mypy . # strict type checking (mypy.ini)
uv run black . # format (CI runs `black --check .`)
make -C docs html # build Sphinx docs (also `make -C docs doctest`)
uv build # build sdist/wheelRun pytest from the repo root: doctests and file-based tests open paths like tests/yaml/hello-world.txt relative to the working directory.
The whole library is frontmatter/__init__.py (public API + Post) and frontmatter/default_handlers.py (format handlers).
- Handlers (
BaseHandlersubclasses:YAMLHandler,JSONHandler,TOMLHandler) do the format-specific work:detect(regex match onFM_BOUNDARY),split(frontmatter vs. content),load(text → dict),export(dict → text), andformat(assemble delimiters + metadata + content). Custom formats are added by subclassingBaseHandler. - Detection order: the module-level
handlerslist in__init__.pyis tried in order YAML → JSON → TOML; the first whosedetectmatches wins. Passinghandler=toload/loads/parseskips detection. - TOML is optional: if the
tomlpackage isn't installed,TOMLHandlerisNoneand is filtered out ofhandlers. - YAML uses the C-accelerated
CSafeLoader/CSafeDumperwhen available, falling back to the pure-Python safe versions. Postholdscontent,metadata(dict, proxied viapost[key]), and thehandlerused to parse it.dumpsuses the post's handler unless one is passed, defaulting to YAML.frontmatter/util.py:u()normalizes bytes/str to unicode and converts\r\n→\n;is_readable/can_opendecide whether an argument is a file-like object or a path.
- Doctests are a core part of the suite. Docstrings in
frontmatter/and the code blocks inREADME.mdare executed (via--doctest-modules/--doctest-globandtests/test_docs.py). Changing output formatting or README examples requires keeping them in sync.frontmatter/conftest.pyinjectsfrontmatterinto the doctest namespace. - Fixture-file tests (
tests/test_files.py): every*.md/*.txtundertests/is loaded and compared against a sibling<name>.result.json(thePost.to_dict()output). To add a case, drop a file in the relevant format directory and runpython tests/stub_tests.pyfrom insidetests/to generate missing result files (it never overwrites) — then verify the generated JSON is correct. tests/unit_test.pyholds the conventional unit tests.
mypy runs in strict mode on the package only (tests, docs, examples are excluded).
Publishing to PyPI happens automatically via GitHub Actions (.github/workflows/publish.yml) when a GitHub release is created. Bump version in pyproject.toml first.