Skip to content

Source code

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.15 and Poetry within the range declared in pyproject.toml. Run yarn python:setup to install the locked tools and use poetry run for Python commands.
  • Keep dependency declarations in pyproject.toml and commit poetry.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 --path and 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 under src/tests/. Repository policy validators belong in src/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>, and Version: YYYYMMDD in 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 self and cls, 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, and finally attached 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.toml preserve their testing APIs.
  • Never explicitly raise inside a protected try body. 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:python for 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:python for pytest with statement and branch coverage, JUnit, Cobertura, and HTML reports under .reports/python/. Require complete coverage of the maintained Python tools. Use yarn presentation:test for focused presentation tests.
  • Run yarn check before handing off broad changes. The hosted lint:python and test:python jobs 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:install only 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-metadata hook last, after every hook that can modify Markdown. It invokes yarn docs:refresh over the complete registry even when an earlier hook reports edits. Review and stage automatic source and metadata changes together before retrying a commit. Use yarn docs:refresh manually when hooks are not installed, and yarn version:bump for coordinated package versions, as described in the release guide.

Author

Laurent Declercq l.declercq@agon-innovation.ch

Version

Version: 20260923