Code Conventions

• Creating or updating features under src/PACKAGE_NAME/<feature_name>/.
• Adding or updating tests for a feature.
• Creating CLI entrypoints or tasks.
• Adjusting project configuration related to Pyright, Black, pytest, or Poe tasks.

Structure and file placement

• Use a feature-first approach:

  • Group related code under src/PACKAGE_NAME/<feature_name>/.
  • If a feature is self-contained, put its unit tests in the same feature folder, e.g.:
    • src/PACKAGE_NAME/feature/feature.py
    • src/PACKAGE_NAME/feature/feature_test.py

• Example of a feature structure

  • src/PACKAGE_NAME/feature/
    • main.py
    • main_test.py
    • types.py (optional, may contain additional types used in the feature)
    • api/
      • entity_api.py (e.g fetching an endpoint)
    • models/
      • entity.py (e.g. Pydantic models)
      • entity_test.py (may contain or import mocks to test the model)
    • services/
      • entity_service.py
      • entity_service_test.py

• Do not create a separate top-level tests folder.

• Keep module and test names descriptive and consistent.

Additional utilities

• Additional utilities that are meant to be shared project-wise, go in a special feature-folder called utils
• This has a different structure than other feature-folders, as it contains folders divided by purpose
• utils
  • web/
    • parser.py
    • parser_test.py
    • webdriver.py
    • webdriver_test.py

Typing rules

• Use clear, explicit typing everywhere:
  • Avoid untyped containers like dict, list, tuple, set.
  • Prefer precise types such as dict[str, str], list[int], tuple[str, int], etc.
• For complex types, consider defining custom type aliases or data classes to improve readability.
• Inference is encouraged over explicit typing when typing is sound.
• For functions, always provide type annotations for parameters, but return types can be omitted if they are None or if the function has sound typing and is well-named.
• Treat Pyright strict mode seriously:
  • Fix type issues by improving annotations, adding type guards, or restructuring code.
  • Prefer explicit checks and type guards (e.g. isinstance checks) over # type: ignore.
  • Only use # type: ignore as a last resort, with a short comment explaining why.
• For third-party libraries without type annotations:
  • Prefer installing appropriate type stub packages (e.g. from types-… distributions) when available.
  • If no stubs exist, consider creating minimal stubs in src/typings for the used parts of the API.

CLI and scripts

• When a file is meant to be run from the command line:
  • Do not use the if __name__ == "__main__": pattern.
  • Instead, expose a clear function (e.g. main()) inside a module.
  • Register this function in [project.scripts] so it becomes a CLI entrypoint.
• If the script is not simple Python or better modeled as a task:
  • Add it under [tool.poe.tasks] with an appropriate name.
  • Prefer Poe tasks for orchestration or shell-like commands, and Hatch scripts for Python entrypoints.

Testing conventions

• If a feature is self-contained, add a unit test module next to it:
  • feature.py → feature_test.py in the same feature directory.
  • Test functions should be named like test_my_feature() when testing my_feature() in feature.py.
• Follow the existing pytest configuration:
  • Tests live under src, matching *_test.py.
• When adding or changing behavior:
  • Add at least one unit test for non-trivial logic.
  • Prefer focused, readable tests over large, multi-purpose ones.

Tools and commands

When proposing changes, the agent should keep these commands in mind:

• uv run poe test → run pytest tests.
• uv run poe lint → run Black in check mode.
• uv run poe lint-fix → format code with Black.
• uv run poe typecheck → run Pyright on ./src.

General guidance for the agent

• Prefer small, incremental changes aligned with the feature-first layout.
• Maintain readability and consistency over cleverness.
• When in doubt about structure or naming, favor clarity and alignment with these conventions.