Coding Standards

This page describes the development checks used in the Sophios repository. For environment setup, start with the Developer Install Guide.

Type Checking

Sophios uses mypy type annotations throughout the source tree. The active mypy configuration lives in pyproject.toml.

Run the same broad paths used by CI:

mypy src/ examples/ tests/

When adding or changing public APIs, prefer explicit types at the API boundary. Internal helper code can still be compact, but typed inputs and return values make the workflow compiler and Python API much easier to maintain.

Docstrings

Docstrings should explain what a function or class is responsible for, what its important arguments mean, and what callers can expect back.

Use docstrings to clarify behavior, not to repeat obvious type information. For example, this is useful because it explains the naming convention:

def step_name_str(yaml_stem: str, i: int, step_key: str) -> str:
    """Return the stable internal name for one workflow step."""
    ...

Tests

Tests live under tests/ and use pytest markers declared in pyproject.toml:

  • fast: quick API, schema, and unit-style checks,

  • serial: tests that should not run in parallel,

  • slow: workflow or integration checks that can take longer.

Useful local commands:

pytest -m fast
pytest tests/test_python_api.py tests/test_tool_builder.py -q
pytest -m serial
pytest -m "not serial" --workers 8

Runtime workflow tests may need Docker or Podman and can pull container images. Prefer the focused API tests while iterating on Python API or documentation changes.

Coverage

The repository includes pytest-cov. To generate a coverage report, add --cov and use the checked-in .coveragerc:

pytest -m fast --cov --cov-config=.coveragerc

Linting

Sophios uses pylint for style, formatting, and common mistake detection. The configuration lives in pyproject.toml.

Run:

pylint src/ examples/**/*.py tests/

The current configured maximum line length is 120 characters.

CI Checks

GitHub Actions workflows live under .github/workflows/. The main Linux CI workflow installs .[all_except_runner_src] and runs:

  • mypy src/ examples/ tests/,

  • pylint src/ examples/**/*.py tests/,

  • focused Python API and workflow tests,

  • selected runtime workflow tests.

Before pushing a broad change, run the focused checks that match the area you touched. For Python API or docs changes, the most useful baseline is:

sphinx-build -b html docs docs/_build/html
pytest tests/test_python_api.py tests/test_tool_builder.py -q