python-conventions

name	python-conventions
description	Python style, tooling, and testing conventions for this repo — ruff/black formatting, pylint config, NumPy docstrings, logging, and the pytest layout (unit/integration/acceptance) with the single-JVM constraint. Use before writing or reviewing any Python change here so it passes CI on the first try.

Python conventions

Formatting & linting (must pass CI)

• ruff is the formatter and primary linter. Line length 88, black-compatible.
  • Format: make format = ruff check --select I --fix (import sort) + ruff format .
  • Lint: make ruff-lint = ruff check .
• pylint also runs: make pylint = pylint examples/ rocketserializer/ tests/. The disabled checks are in pyproject.toml [tool.pylint] (e.g. missing docstrings, too-many-locals/arguments, raise-missing-from, fixme). Don't re-enable them ad hoc.
• CI (.github/workflows/linter.yml) runs ruff format --check, ruff check, and pylint on Python 3.9. Run make lint locally first.
• Supported Python: 3.8–3.12 (requires-python = ">= 3.8"). Don't use syntax newer than 3.8.

Docstrings & logging

• NumPy-style docstrings with Parameters / Returns / Raises sections — match the existing modules (_helpers.py, ork_extractor.py).
• Every module defines logger = logging.getLogger(__name__). Log instead of print. User-facing CLI messages are prefixed with the command name, e.g. [ork2json] ....
• Public functions raise precise exceptions with actionable messages (FileNotFoundError, ValueError); the CLI surfaces them.

Testing

• Layout: tests/unit/, tests/integration/, tests/acceptance/.
• Run: make tests (pytest); CI: pytest tests/ -v --timeout=120 (the --timeout guards against a hung JVM). One case: pytest tests/acceptance/test_ork_extractor.py -k valetudo -v.
• Single-JVM rule: JPype (<1.5) can't restart a JVM in-process, so tests/conftest.py opens exactly one OpenRocketSession and caches every example's settings as fixtures. Never open another session in a test.
• Acceptance tests are golden-file comparisons against examples/<name>/parameters.json. Intentional output changes require regenerating and reviewing those files.

Dependencies

Runtime deps are in requirements.in (consumed by pyproject.toml dynamic dependencies); dev tools in requirements-dev.txt. Add runtime deps to requirements.in, not directly to pyproject.toml.