|
| 1 | +--- |
| 2 | +description: 'Python coding conventions and guidelines' |
| 3 | +applyTo: '**/*.py' |
| 4 | +--- |
| 5 | + |
| 6 | +# Python Coding Conventions |
| 7 | + |
| 8 | +## General Instructions |
| 9 | +- All configuration **must be provided via environment variables**. |
| 10 | +- Do not hardcode configuration values. |
| 11 | +- Write maintainable, readable, and predictable code. |
| 12 | +- In `pyproject.toml`: |
| 13 | + - Use `*` for **minor versions only** |
| 14 | + ✅ `django==4.2.*` |
| 15 | + ❌ `django==^4.2.2` |
| 16 | + |
| 17 | +- Use consistent naming conventions and follow language-specific best practices. |
| 18 | + |
| 19 | +## Python Instructions |
| 20 | +- Use type annotations (PEP 484) - except in the `tests/` folder. |
| 21 | +- All public functions, methods, and classes **must include [Google-style docstrings](https://google.github.io/styleguide/pyguide.html)**. |
| 22 | +- **Do not add inline comments**; rely on clear code and docstrings instead. |
| 23 | +- Function and variable names must be explicit and intention-revealing. |
| 24 | +- `pyproject.toml` is the source of truth for code quality rules. Generated code must not violate any configured rules. |
| 25 | +- **ruff** is the primary linter for general Python style and best practices. |
| 26 | +- **flake8** is used exclusively to run: |
| 27 | + - `wemake-python-styleguide` - Enforces strict Python coding standards ([docs](https://wemake-python-styleguide.readthedocs.io/en/latest/)) |
| 28 | + - `flake8-aaa` - Validates the AAA pattern in tests |
| 29 | +- Follow PEP 8 unless explicitly overridden by ruff. |
| 30 | +- Prefer simple, explicit code over clever or compact implementations. |
| 31 | + |
| 32 | +## Testing |
| 33 | +- Use pytest only. |
| 34 | +- Tests must be written as **functions**, not classes. |
| 35 | +- Test files and functions must use the `test_` prefix. |
| 36 | +- Follow ***AAA(Arrange - Act - Assert)*** strictly. See the [flake8-aaa documentation](https://flake8-aaa.readthedocs.io/en/stable/index.html). |
| 37 | +- Do **not** use `if` statements or branching logic inside tests. |
| 38 | +- Prefer fixtures over mocks whenever possible. |
| 39 | +- Avoid duplicating test logic; extract shared setup into fixtures. |
| 40 | +- Use `mocker` only when mocking is unavoidable. |
| 41 | +- Never use `unittest.mock` directly. |
| 42 | +- Always use `spec` or `autospec` when mocking. |
| 43 | +- Use `@pytest.mark.parametrize` tests when testing permutations of the same behavior. |
0 commit comments