Custom lint checks for Beda Software projects — the conventions ruff and mypy don't cover. Each check is a
standalone command and a pre-commit hook; pick the ones a project wants. Requires
Python 3.11+ (the checks read their config with tomllib); the checked code can target any Python 3 version.
| Hook / command | Language | What it checks | Style guide |
|---|---|---|---|
call-tree-order |
Python | Each function sits below its last caller (BCT001) |
good / bad |
function-verb-names |
Python | Function names start with a verb (BVN001); bool functions read as predicates (BVN002) |
good / bad |
Each rule's style guide is a pair of files under examples/: good.py passes, bad.py shows every
finding with the fix in a comment. Tests run the checks on both, so the examples always match what the checks do.
A module should read top-down like a call tree: the public entry point first, then its helpers in the order they're first used, each helper's own helpers below it. The check flags any function or method defined above a function that calls it:
app/orders.py:12: BCT001 `_total` is defined above its caller `build_invoice` (line 30); move helpers below their last caller
See the style guide: good / bad.
What counts:
- A call or a reference to the function (
sorted(items, key=_key)) inside another function's body. - Methods are checked within their class, through
self.x,cls.xandClassName.x. - Functions that call each other in a cycle are not ordered among themselves.
- Decorators and default values run at definition time, so they are not counted as uses.
@propertygetters are read as attributes and never need to sit below their users.
# .pre-commit-config.yaml
repos:
- repo: https://github.com/beda-software/beda-lint
rev: main
hooks:
- id: call-tree-order
# optional, for an existing codebase:
args: [--baseline, lint/order-baseline.txt]While beda-lint is in active development there are no release tags, so pin main. pre-commit warns about a mutable
rev and caches the first checkout; run pre-commit clean to pick up newer checks.
No install needed with uv:
uvx --from git+https://github.com/beda-software/beda-lint call-tree-order src testsOr add it as a dev dependency (uv add --dev git+https://github.com/beda-software/beda-lint, or the poetry
equivalent) and call call-tree-order <paths> from a Makefile or CI.
A legacy codebase usually has hundreds of violations. Rather than reorder everything at once, record the existing ones in a baseline file: the check then skips them and fails only on new violations, and old modules get fixed as they're touched.
-
Create the baseline from the folder you will always run the check from (usually the project root), over every path the check will cover:
uvx --from git+https://github.com/beda-software/beda-lint \ call-tree-order src tests --baseline lint/order-baseline.txt --update-baseline
It writes one
path::symbolline per existing violation, sorted, for example:src/billing/invoices.py::_total src/billing/invoices.py::InvoiceBuilder._add_line -
Commit the baseline next to the code.
-
Wire the check in with the same
--baselinepath — the pre-commit hook above, or a Makefile/CI step:call-tree-order src tests --baseline lint/order-baseline.txt
-
Shrink it over time. After moving some helpers below their callers, rerun step 1 and commit the shorter file. Always regenerate over the whole tree, never from pre-commit: pre-commit passes only the changed files, so a baseline written from them would drop every other entry.
How entries match:
- No line numbers: a baselined function stays skipped when code above it changes, or when it moves within its file.
- A new violation in a baselined file still fails, and so does a baselined function once it is renamed or its file moves.
- Paths are relative to the working directory, so create and check the baseline from the same folder.
A function does something, so its name starts with what it does: fetch_patient, _build_payload, sync. A
function returning bool answers a question about its argument, so its name reads as a statement: is_closed,
has_slots, should_retry, matches_requirement. An imperative name on a bool function (record_satisfier() -> bool)
promises an action it does not take.
app/billing.py:12: BVN001 `invoice_total` does not start with a verb; name it for what it does (`fetch_`, `build_`, ...) or add `invoice` to extra-verbs
app/billing.py:30: BVN002 `check_paid` returns bool, so name it as a statement about its argument: `is_`, `has_`, `should_`, `can_`, or a third-person verb such as `matches_`
See the style guide: good / bad, each bad name with its fix.
How a name is read:
- The first word counts, after leading underscores, split on
_or camelCase:_fetch_x→fetch,setUp→set,Total→total. - BVN001: the first word must be in the verb list — the built-in
verbs.txtplusextra-verbs— or a predicate prefix (is_,has_, ...). A third-person form (matches_,records) passes only on a bool function, sorecords() -> listis flagged. - BVN002: a function returns bool when it is annotated
-> bool,TypeGuard[...]orTypeIs[...], or — without an annotation — when everyreturngivesTrue/False, a comparison,not …,and/orof those, a call such asisinstance,any,all,bool, or a call to a predicate-named function (self._is_valid()). Its first word must beis,are,has,have,can,should,does, anextra-predicate-prefixesentry, or the third-person form of a listed verb (matches,applies,belongs). - Exempt: dunder methods,
main,@propertyand its setter/getter/deleter,@cached_property,@overloadstubs,@pytest.fixturefunctions, names matching*_op(Aidbox operations), and aiohttp lifecycle hooks registered in the same module —app.cleanup_ctx.append(db),app.on_startup += [warmup]and the other app signals. A hook registered from another module is not seen; list it inignore-patternsor add# noqa: BVN001.test_*passes becausetestis a verb.
Optional, in the pyproject.toml of the folder the check runs from:
[tool.beda-lint.function-verb-names]
# Verbs specific to the project, added to the built-in list.
extra-verbs = ["rehydrate", "debit"]
# Extra bool-name prefixes, besides is/are/has/have/can/should and third-person verbs.
extra-predicate-prefixes = ["needs"]
# Decorated functions named by framework convention.
ignore-decorators = ["sdk.operation", "sdk.subscription"]
# Shell-style globs over the full function name.
ignore-patterns = ["m_*", "action_*", "*_op", "*_handler"]An unknown key or a non-list value stops the run with an error, so a typo never silently disables a setting. A verb
missing from the built-in list that most projects would use belongs in verbs.txt — open a PR.
# .pre-commit-config.yaml
repos:
- repo: https://github.com/beda-software/beda-lint
rev: main
hooks:
- id: function-verb-names
args: [--baseline, lint/names-baseline.txt]uvx --from git+https://github.com/beda-software/beda-lint function-verb-names src testsThe baseline works as for call-tree-order: entries are path::Class.function, so see
Adopting it in a legacy project — use a separate baseline file per check.
Every check honours # noqa: CODE on the line it reports — the def line, not a decorator line:
def dt(time_str: str) -> datetime: # noqa: BVN001 — short on purpose, used in test tablesSeveral codes can share one comment with ruff's: # noqa: E501, BVN001. With ruff's RUF100 (unused noqa)
enabled, tell ruff these codes are external so it keeps them:
[tool.ruff.lint]
external = ["BVN", "BCT"]The checks are also flake8 plugins, so an editor running flake8 underlines findings as you type. Baselines are not
supported there: use flake8's per-file-ignores for legacy files, and keep the commands above for pre-commit and CI.
flake8 also honours a bare # noqa without codes, which the commands ignore.
In VS Code, install the Flake8 extension and
beda-lint into the project environment (uv add --dev git+https://github.com/beda-software/beda-lint), then limit
flake8 to these codes so it does not duplicate ruff:
// .vscode/settings.json
{ "flake8.args": ["--select=BCT,BVN"] }uv sync
uv run pytest
uv run ruff format --check . && uv run ruff check . && uv run mypyA new check goes in beda_lint/<check>.py with a main(), a [project.scripts] entry in pyproject.toml, a
plugin class in beda_lint/flake8_plugin.py with its flake8.extension entry point, a hook
in .pre-commit-hooks.yaml, tests in tests/, a style guide in examples/<check>/good.py and bad.py (registered
in tests/test_examples.py, which fails until every script in [project.scripts] has a folder), and a row in the
table above.