Run commands

Tests:
```
poetry run pytest -q
```
Lint:
```
poetry run ruff check .
```
Lint fix:
```
poetry run ruff check . --fix
```
Type check:
```
poetry run mypy .
```
```
rg
```
(ripgrep) is installed in
```
/usr/bin/rg
```
and is available on PATH.

Quick diagnostics

Venv path:
```
poetry env info --path
```

Python used:

poetry run python -c "import sys; print(sys.executable)"

Tool path:

poetry run which ruff

poetry run which pytest

Coding Guidelines

Follow PEP 8 via
```
ruff --fix
```
.
All imports should be at the top of the file, and ordered as follows:
1. Standard library imports
2. Third-party imports
3. Local application imports
4. if TYPE_CHECKING, imports for type hints only
Always use British English spelling for code and comments.
Since we use from future import annotations, type hints generally should be strings. Use TYPE_CHECKING to import types that are only needed for type hints.
Self documenting function names are better than comments.
Prefer small, verb-noun functions (≈ 5–20 lines).
Respecting SRP is vital.
Prefer keyword only arguments for public methods, unless there is only a single obvious argument.
Guard clauses beat deep nesting. Replace pyramids of if … else with early returns and continue statements.
Code must be DRY, duplication is not acceptable.
Side-effect–free functions are preferred. When possible make them pure (no I/O, no globals).
Create encapsulation, i.e account.debit(£5) is better than account.balance -= 5.
Separate command from query. Functions that change state shouldn’t also return useful data; returning None makes intent explicit.
Implement dependency inversion via dependency injection.
Favour composition over inheritance.
Readable is better than clever. Always favour easy to understand code over clever tricks.
Docstrings and comments should explain why. Code should explain what. Code should be self-documenting, comments used sparingly.
Whenever you touch a file, prune dead code, rename unclear vars, add a missing test.
Use ruff and mypy to check code style and type hints.

Testing Guidelines

Run tests
- python -m pytest -q
Location & naming
- Keep everything in the root-level tests/ directory.
- Every file starts with test_.
  - Single-file class example: tests/test_foo_service.py.
  - Large class: create a folder (e.g. tests/foo_service/) and split by behaviour (test_foo_service_behaviour_error.py, etc.).
Structure inside a file
- Group related checks in a class, e.g. class TestErrorDetection:.
- Every test method begins with test_.
- If a file grows too long, split it—never let one file balloon.
Docstring rule
- Exactly one docstring per test method.
- Must start with “Verify …”
  - """Verify raises exception when widget is not found."""
Fixtures
- Live in tests/fixtures/.
- Loaded automatically as pytest plug-ins—inject them by name.
- Always type-hint injected fixtures; wrap the import in TYPE_CHECKING if it isn’t needed at runtime.
Good examples
- See tests/components_tests/model/ for reference-quality patterns.

Coding Guidelines

Follow PEP 8 via

ruff --fix

All imports should be at the top of the file, and ordered as follows:

Standard library imports
Third-party imports
Local application imports
if TYPE_CHECKING, imports for type hints only

Always use British English spelling for code and comments.

Since we use from future import annotations, type hints generally should be strings. Use TYPE_CHECKING to import types that are only needed for type hints.

Self documenting function names are better than comments.

Prefer small, verb-noun functions (≈ 5–20 lines).

Respecting SRP is vital.

Prefer keyword only arguments for public methods, unless there is only a single obvious argument.

Guard clauses beat deep nesting. Replace pyramids of if … else with early returns and continue statements.

Code must be DRY, duplication is not acceptable.

Side-effect–free functions are preferred. When possible make them pure (no I/O, no globals).

Create encapsulation, i.e account.debit(£5) is better than account.balance -= 5.

Separate command from query. Functions that change state shouldn’t also return useful data; returning None makes intent explicit.

Implement dependency inversion via dependency injection.

Favour composition over inheritance.

Readable is better than clever. Always favour easy to understand code over clever tricks.

Docstrings and comments should explain why. Code should explain what. Code should be self-documenting, comments used sparingly.

Whenever you touch a file, prune dead code, rename unclear vars, add a missing test.

Use ruff and mypy to check code style and type hints.

Testing Guidelines

Run tests

python -m pytest -q

Location & naming

Keep everything in the root-level tests/ directory.
Every file starts with test_.
- Single-file class example: tests/test_foo_service.py.
- Large class: create a folder (e.g. tests/foo_service/) and split by behaviour (test_foo_service_behaviour_error.py, etc.).

Structure inside a file

Group related checks in a class, e.g. class TestErrorDetection:.
Every test method begins with test_.
If a file grows too long, split it—never let one file balloon.

Docstring rule

Exactly one docstring per test method.
Must start with “Verify …”
- """Verify raises exception when widget is not found."""

Fixtures

Live in tests/fixtures/.
Loaded automatically as pytest plug-ins—inject them by name.
Always type-hint injected fixtures; wrap the import in TYPE_CHECKING if it isn’t needed at runtime.

Good examples

See tests/components_tests/model/ for reference-quality patterns.

Run commands

Run commands

Quick diagnostics

Coding Guidelines

Testing Guidelines

Related Skills

Markdown Converter

Nano Banana Pro

1password

Run commands

Quick diagnostics

Coding Guidelines

Testing Guidelines