Python tooling guidance
These conventions adapt Agon Skeleton’s Python guidance and validators to Ātrium’s development tools. They apply equally to source, tests, fixtures, mocks, private functions, nested helpers, and the validators themselves.
Environment and ownership
- Use Python
>=3.12,<3.15and Poetry within the range declared inpyproject.toml. Runyarn python:setupto install the locked tools and usepoetry runfor Python commands. - Keep dependency declarations in
pyproject.tomland commitpoetry.lock. Pin direct dependencies exactly. Keep presentation dependencies separate from quality tools. Do not maintain a second pip requirements file or recreate an existing developer environment. - Inspect
poetry env info --pathand the selected Python before changing environments. Support local, external, and compatible Conda-selected Poetry environments. Keep environments, caches, and reports ignored. - Keep maintained code under
src/scripts/and tests undersrc/tests/. Repository policy validators belong insrc/scripts/quality/python/. CI helper directories remain reserved for direct CI entry points.
Source and test contracts
- Give every module and class one compact punctuated purpose docstring. Keep the module’s purpose,
Author: Laurent Declercq <l.declercq@agon-innovation.ch>, andVersion: YYYYMMDDin the repository’s separate comment header, without@prefixes. - Give every callable a complete multiline docblock with standalone opening and closing delimiters, a punctuated purpose, one blank line, all explicit parameters except
selfandcls, exactly one:return:or:yield:field, and documented stable failures. Order fields as parameters, result, and failures. End field descriptions with periods. Tests, fixtures, private methods, callbacks, and empty functions follow the same rules. - Keep the docblock attached to the first executable statement. Separate sibling control-flow blocks from the statements before and after them with one blank physical line. Separate each non-initial return from its preceding executable sibling. Keep
elif,else,except, andfinallyattached to their owning block. - Use complete annotations and strict Pyright for all Python source and tests. Narrow external JSON before use, and model stable records explicitly. Missing third-party stub packages may follow the declared Pyright setting. Do not exclude owned code or silence unknown types instead of correcting them.
- Use Ruff for formatting, imports, correctness, and maintainability. Preserve the configured four-space indentation and 120-character line length. Keep diagnostics enabled for tests. The narrow unittest assertion and private-policy test allowances in
pyproject.tomlpreserve their testing APIs. - Never explicitly raise inside a protected
trybody. Validate external responses through a dedicated boundary and document its stable failures. - Preserve content-based media caches, output staging, and cache-lock cleanup. Tests must mock speech and encoder boundaries instead of contacting the speech service or replacing delivered videos.
Quality and hooks
- Run
yarn lint:pythonfor Poetry lock validation, Ruff, imported header/docblock/layout validators, and strict Pyright. Its baseline includes tracked and untracked maintained Python files and all tests. - Run
yarn test:pythonfor pytest with statement and branch coverage, JUnit, Cobertura, and HTML reports under.reports/python/. Require complete coverage of the maintained Python tools. Useyarn presentation:testfor focused presentation tests. - Run
yarn checkbefore handing off broad changes. The hostedlint:pythonandtest:pythonjobs invoke Poetry directly in Python 3.14 containers, after their dedicated cache warmup. Follow CI guidance for the runtime and download cache. Local Yarn commands remain convenience shortcuts. - Pre-commit installation is optional. Use
yarn hooks:installonly when the developer chooses to enable the local hook. The version-header hook runs before validation and updates modified files using the current Zurich date. Limit edits to the leading source metadata comment or final Markdown Version footer. Normalize the metadata field spelling and punctuation according to coding standards. Never rewrite fixture strings, code examples, other body content, package SemVer, or changelog release dates. - Keep the
documentation-metadatahook last, after every hook that can modify Markdown. It invokesyarn docs:refreshover the complete registry even when an earlier hook reports edits. Review and stage automatic source and metadata changes together before retrying a commit. Useyarn docs:refreshmanually when hooks are not installed, andyarn version:bumpfor coordinated package versions, as described in the release guide.
Author
Laurent Declercq l.declercq@agon-innovation.ch
Version
Version: 20260923