mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2026-11-13 09:13:30 +01:00
63 lines
2.2 KiB
Markdown
63 lines
2.2 KiB
Markdown
  
|
---
|
||
|
|
name: filename-conventions
|
||
|
|
description: Use when creating, renaming, or proposing any new file in this repository. Mandatory filename rules derived from [tool.eos-filename-linter] in pyproject.toml.
|
||
|
|
---
|
||
|
|
|
||
|
|
# Filename Conventions
|
||
|
|
|
||
|
|
**Filename conventions are mandatory.** All new and renamed files must comply
|
||
|
|
with the rules configured in `pyproject.toml`. The custom filename linter is the
|
||
|
|
authoritative source; if this document and the configuration appear
|
||
|
|
inconsistent, follow the configuration.
|
||
|
|
|
||
|
|
## Procedure
|
||
|
|
|
||
|
|
1. Inspect `[tool.eos-filename-linter]` in `pyproject.toml`.
|
||
|
|
2. Find the first matching rule for the file's repository-relative path.
|
||
|
|
3. Apply that rule's regex, `allowed_names`, exclusions, and max length.
|
||
|
|
4. Do not invent alternative conventions or infer acceptability from valid Python.
|
||
|
|
5. Do not weaken the linter configuration to accommodate a filename.
|
||
|
|
|
||
|
|
## Python source modules (`src/akkudoktoreos/`)
|
||
|
|
|
||
|
|
- Follow the configured pattern for that directory.
|
||
|
|
- Where lowercase-alphanumeric is required: lowercase letters and digits only,
|
||
|
|
no underscores or hyphens.
|
||
|
|
- Preserve listed `allowed_names` (e.g. `__init__.py`).
|
||
|
|
- Do not rename existing modules for stylistic preference.
|
||
|
|
|
||
|
|
## Pytest modules (`tests/`)
|
||
|
|
|
||
|
|
Where the rule requires `test_` + lowercase alphanumerics:
|
||
|
|
|
||
|
|
- Start with `test_`, then lowercase letters/digits only.
|
||
|
|
- No underscores or hyphens after the prefix.
|
||
|
|
- Keep `.py`.
|
||
|
|
- Respect configured exceptions/exclusions.
|
||
|
|
- If a separate rule applies (e.g. `single_test_*.py`), follow that rule.
|
||
|
|
|
||
|
|
| Valid | Invalid |
|
||
|
|
|---|---|
|
||
|
|
| `test_adapterdevice.py` | `test_adapter_device.py` |
|
||
|
|
| `test_geneticforecastcoverage.py` | `test_genetic_forecast_coverage.py` |
|
||
|
|
| `test_invertercontrol.py` | `test_inverter-control.py` |
|
||
|
|
|
||
|
|
## Python scripts (`scripts/`)
|
||
|
|
|
||
|
|
Where lowercase snake_case is required:
|
||
|
|
|
||
|
|
- Lowercase letters and digits, underscores to separate words, no hyphens, `.py`.
|
||
|
|
- Valid: `lint_filenames.py`
|
||
|
|
- Invalid: `lint-filenames.py`, `LintFilenames.py`
|
||
|
|
|
||
|
|
## Filename length
|
||
|
|
|
||
|
|
Respect the max length from the applicable rule, else the global default in
|
||
|
|
`pyproject.toml` / linter. The limit includes the extension.
|
||
|
|
|
||
|
|
## Verify
|
||
|
|
|
||
|
|
```bash
|
||
|
|
uv run python scripts/lint_filenames.py
|
||
|
|
uv run python scripts/lint_filenames.py path/to/file.py
|