Write a custom check¶
This guide shows how to add your own rule to LaNorme as a plugin: a small Python module that registers a check, which LaNorme then discovers and runs alongside the built-ins. Use it to encode a house rule the bundled normes do not cover, your domain vocabulary, a project-specific structural invariant, or any mechanical standard your team agrees on.
You do not fork LaNorme. A check is an ordinary object; you ship it in your own package and point LaNorme at it.
The Check protocol¶
A check is any object with four members:
name(str): a unique identifier, used by--check <name>and in output.description(str): one line describing what the check enforces.rules(list of str): one entry per rule code, each"CODE-001: one line".check(self, scan: Scan) -> CheckResult: scans the tree and returns the findings.
check receives the lanorme.scan.Scan for the pass: scan.root is the
directory being checked (a Path), and the scan also carries the subtree
scope, the exclude globs in force, the project's source_root and the run's
parse cache. LaNorme activates the scan around the call, so the readers in
lanorme.sources and lanorme.discovery prune what it prunes; a check reads
scan.root and calls them. check returns a CheckResult carrying two lists
of Violation: violations (hard findings that fail the build) and
warnings (advisories that report but keep the exit code at 0).
from lanorme import CheckResult, Violation
from lanorme.scan import Scan
class MyCheck:
name = "my_check"
description = "What it enforces, in one line"
rules = ["MYCODE-001: the rule, in one line"]
def check(self, scan: Scan) -> CheckResult:
violations: list[Violation] = []
# inspect files under scan.root
return CheckResult.from_findings(check=self.name, violations=violations)
CheckResult.from_findings(check=, violations=, warnings=) builds the result
from the two lists, both empty by default. Its status is derived from them,
never stored: any violation is FAIL, otherwise any warning is WARN,
otherwise PASS, so the header LaNorme prints always agrees with the
findings. CheckResult(check=, violations=, warnings=) builds the same
result; its status= argument is deprecated and ignored, with a
DeprecationWarning.
The previous entry point, run(self, *, src_root: str), is deprecated. A
check that defines run and no check still runs: LaNorme calls run with
the scan active and src_root set to str(scan.root), and emits a
DeprecationWarning once per check class. Implement check(scan) before the
old entry point is removed.
A Violation records where and what:
Violation(
file="src/utils.py", # path, relative to scan.root
line=12, # 1-based line, or 0 for a whole-file or path finding
rule="MYCODE-001", # the bare code; the runner adds the description
message="What is wrong here",
fix="What to do about it",
)
rule may be the bare code ("MYCODE-001") or the full declared string
("MYCODE-001: the rule, in one line"). The runner expands a bare code to the
string the check declares in rules, so every output carries the description
and you spell it once per check.
Three optional fields give the finding's extent: column and end_column
(0-based, as ast counts them) and end_line (1-based, inclusive). Fill all
three from the node you report with **locate(node):
from lanorme.sources import locate
Violation(
file=module.relative,
line=node.lineno,
rule="MYCODE-001",
message="What is wrong here",
fix="What to do about it",
**locate(node),
)
A node without positions gives None for each. The JSON and ndjson records
carry these fields, derive the finding's scope (span, line or file)
from them, and the github format turns them into annotation columns. See
finding records.
Register the check¶
Call register() with an instance at import time. That is what makes LaNorme
find and run it.
from lanorme import register
register(MyCheck())
Each check needs a name of its own: registering a second, different check
under a name already taken raises lanorme.errors.UsageError (exit 2 at the
CLI) rather than letting the later one silently replace the earlier.
Registering the same instance twice is harmless.
The registered instance is a template. The run never configures or runs it in
place: every pass (the whole-tree pass and one per config region) works on a
deep copy configured from that pass's config, so settings cannot leak from
one region, or one run, into the next. A check must therefore survive
copy.deepcopy, which rules out holding an open file or a lock on the
instance.
A check that reads configuration may also implement configure(self, *,
settings), which receives its [tool.lanorme.<name>] table before the run. See
Configuring a check below.
Read sources through lanorme.sources¶
Read Python files through lanorme.sources, never Path.rglob. The module
walks the tree with the same pruning as discovery (the built-in never-source
directories such as .venv, node_modules, __pycache__, dist and
build, plus the user's exclude globs, so an excluded subtree is never
read), decodes each file the way the interpreter does (a UTF-8 BOM and a
coding: cookie are honoured) and parses it once per run. Every check then
receives the same Module, so a run costs one parse per file rather than one
per check.
from lanorme.sources import iter_parsed_modules
for module in iter_parsed_modules(scan.root):
module.path # Path to the *.py file
module.relative # its path relative to scan.root, posix style
module.source # the decoded text
module.lines # the text split into lines
module.tree # the parsed ast.Module
module.comments # every # comment, read by tokenize
module.docstrings # every module, class and function docstring
module.imports # every module an import statement names
lines, comments, docstrings and imports are views computed on first
use and shared with every other check that reads the same file in the run, so
reach for them rather than tokenising or walking the file again:
module.commentsholds oneCommentper#comment (line,column,tokenas written,textwithout the#, andstandalonewhen it has the line to itself). A#inside a string is never a comment. On the rare source the tokeniser gives up on part-way, the tuple holds the comments before that point andmodule.has_complete_commentsis false.module.docstringsholds oneDocstringper documented module, class and function, inast.walkorder:owner(the node),node(the string constant),textas written,line, andclean(), which equalsast.get_docstring(owner).module.find_docstring(node)looks one up by its owner.module.importsholds oneImportedModuleper module named:import a, bgives two,from x import y, zgives one forxholding both aliases. Each hasnode,module(""forfrom . import y),aliases,levelandis_from.
iter_parsed_modules(root) yields only the files that parse. iter_modules(root)
yields those same Module objects and, for a file the parser rejects,
overflows on, or cannot read, an UnparseableFile (path, relative, reason)
so the check can decide what to do. A check that reports such files emits the
advisory <PREFIX>-000 notice through build_unparseable_notice:
from lanorme.sources import Module, iter_modules, build_unparseable_notice
for item in iter_modules(scan.root):
if isinstance(item, Module):
... # analyse item.tree
else:
warnings.append(build_unparseable_notice(prefix="MYCODE", failure=item))
The notice's rule is MYCODE-000: <reason>, with the reason one of parse
error, too deeply nested or unreadable. A -000 code is a notice, not a
finding: promotion never escalates it and the baseline never records it.
build_skip_notice(prefix=, file=, name=, reason=) builds the same notice for a
file the check skips on its own.
Trees are shared with every other check in the run, so a check must never
mutate one, or read and ast.parse a file itself. Copy the tree first, or
collect what you need without changing nodes.
For files that are not Python, lanorme.discovery.iter_files(root,
suffix=".md") walks the tree with the same pruning and returns the paths,
sorted.
Walk the tree through module.index¶
module.index is the file's NodeIndex: every node grouped by type, from one
walk of the tree that all checks share. Ask it for the nodes you need instead
of calling ast.walk(module.tree):
import ast
for module in iter_parsed_modules(scan.root):
for call in module.index.collect(ast.Call):
... # every call in the file
for function in module.index.functions:
... # every def and async def, nested ones included
collect(*types) returns the nodes whose exact type is one of types.
functions is collect(ast.FunctionDef, ast.AsyncFunctionDef). Both keep
ast.walk order, so a check that switches from a walk reports the same
findings in the same order.
Read names off nodes through lanorme.astnames¶
lanorme.astnames answers the small questions many checks ask of a node:
find_decorator_leaf(decorator)gives the name a decorator resolves to (@app.route("/")givesroute,@abc.abstractmethodgivesabstractmethod), orNone. Calls are looked through unlesscalls=False; subscripts too withsubscripts=True.list_decorator_leaves(node)gives one per decorator of a function or class.build_attr_chain(node)gives the dotted path an attribute spells (hashlib.md5gives("hashlib", "md5")), or().read_str_constant(node)gives the value of a string literal, orNone.
The run context: lanorme.scan.Scan¶
iter_files, iter_dirs, iter_modules and parse_module honour the run's
exclude globs and subtree scope and share one parse cache, but a check never
passes these around: they belong to the current Scan, the one check
receives, which LaNorme activates around the call. A check reads scan.root
and calls the functions. To run a check by hand under the same confinement,
hand lanorme.run_check the scan; it activates the scan around the call and
isolates an exception as a RUN-000 notice, as a full run does:
from lanorme import run_check
from lanorme.scan import Scan
result = run_check(MyCheck(), scan=Scan(root=project_root, excludes=("vendor/*",)))
run_check(check, src_root=str(path)) runs it over that path under whatever
scan is active, and lanorme.run_all takes the same two arguments for every
registered check. A direct MyCheck().check(scan) runs under the scan in
force, not the one passed, so activate it first: with scan.activate():.
Scan.restrict(scope=..., excludes=...) gives a scan confined to a subtree
with more globs, sharing the parse cache. With no scan active, the whole tree
is walked with no excludes. lanorme.scan.get_current_scan() returns the
scan in force.
The current scan lives in a contextvars.ContextVar, so it follows the
context. Whether a new thread starts in its creator's context depends on the
Python version and build (Python 3.14 adds the thread_inherit_context flag),
and a worker outside it walks the whole tree with no excludes and another
parse cache. A check that hands work to threads should run each task in a copy
of its own context:
import contextvars
from concurrent.futures import ThreadPoolExecutor
with ThreadPoolExecutor() as pool:
futures = [pool.submit(contextvars.copy_context().run, scan_part, part) for part in parts]
Take one copy_context() per task: a context can be entered by only one
thread at a time.
Conventions¶
These conventions keep a custom check consistent with the built-ins. The same rules apply whether the check ships inside LaNorme or as your plugin.
- One category prefix per check. A check owns a single rule-code family
(
MYCODE-001,MYCODE-002, ...). Codes are the public surface: people put them inselect,ignore, andper-file-ignores, so treat them as stable. - Hard findings in
violations, advisories inwarnings. Aviolationsentry fails the run (exit code1); awarningsentry reports but leaves the exit code at0. Opinionated or stylistic rules belong inwarnings, so a user can promote them to errors when they choose (seepromote). - Fill the finding lists; never set a status. The status is derived from
violationsandwarnings, so the header LaNorme prints ([FAIL],[WARN],[PASS]) always agrees with the findings. - Cross-file checks declare
scope = "tree". If a finding depends on comparing or aggregating across files, set the class attributescope = "tree". The default"file"scope lets a check run once per config region under per-directory configuration; a tree-scoped check runs once at the project root so a finding split across two regions is not missed. A region pass still starts at the project root and sees only that region's files, somodule.relativekeeps the full path (tests/helpers.py, nothelpers.py) and a path-based exemption such astests/holds inside a nested region. - Default off when opinionated or broad. A rule that fires often on ordinary
code should ship default-off behind an
enabledflag, so users opt in (see Configuring a check). - Raise
UsageErrorfor a user's mistake. A setting that makes no sense is not a crash. Raiselanorme.errors.ConfigError(aUsageErrorthat also carries the offendingkeyand thesourcetable) fromconfigure, orUsageErrorfor any other mistake of the user's, with the message the user needs; the CLI prints it asERROR: ...and exits2. AUsageErrorraised fromcheckis not hidden in aRUN-000notice either. Never print to stderr or callsys.exitfrom a check.
A check must never let an exception escape check. LaNorme isolates a check
that raises and reports it as a RUN-000 warning whose message carries the
exception type and text, so one bug cannot sink the whole run. A clean check
should not rely on that safety net.
A worked example¶
This check fails when a module is named exactly utils.py, on the house rule
that every module should be named after what it does. LaNorme ships the same
rule built in as NAMING-010 in the opt-in naming_clean_code check; it stays
here as the example because it is the smallest complete check.
# house_rules.py
from __future__ import annotations
from lanorme import CheckResult, Violation, register
from lanorme.scan import Scan
from lanorme.sources import iter_parsed_modules
class NoUtilsModule:
name = "no_utils_module"
description = "Modules must have a meaningful name, not 'utils'"
rules = ["HOUSE-001: Module must not be named 'utils.py'"]
def check(self, scan: Scan) -> CheckResult:
violations: list[Violation] = []
for module in iter_parsed_modules(scan.root):
if module.path.name == "utils.py":
violations.append(
Violation(
file=module.relative,
line=0,
rule="HOUSE-001",
message="Module named 'utils.py' has no clear responsibility",
fix="Rename it after what it actually does",
)
)
return CheckResult.from_findings(check=self.name, violations=violations)
register(NoUtilsModule())
With house_rules.py importable (on sys.path or installed), load it with
--plugin and run it:
$ lanorme check src/ --plugin house_rules --check no_utils_module
[FAIL] no_utils_module
VIOLATION: utils.py:0 — Module named 'utils.py' has no clear responsibility
Rule: HOUSE-001: Module must not be named 'utils.py'
Fix: Rename it after what it actually does
--- no_utils_module: 1 violations, 0 warnings ---
Summary: 1 checks — 0 passed, 0 warned, 1 failed.
Findings: 1 error to fix, 0 advisory warnings.
The check emitted the bare code HOUSE-001; the report shows the full rule
string from rules.
The exit code is 1. Rename or remove the file and the run is clean:
$ lanorme check src/ --plugin house_rules --check no_utils_module
All 1 checks passed.
The exit code is 0.
Note
--plugin is repeatable (--plugin a --plugin b), not comma-separated.
Pass the dotted module path, for example --plugin myproject.checks.house_rules.
Make it an advisory¶
To report without failing the build, collect the findings in a warnings
list instead and pass it as warnings:
return CheckResult.from_findings(check=self.name, warnings=warnings)
The run then exits 0, the check shows as [WARN] and each finding is
labelled WARNING: rather than VIOLATION:. A user who wants it to
fail the build can escalate the code with
promote:
$ lanorme check src/ --plugin house_rules --promote HOUSE-001
That turns the advisory into a build-failing error (exit code 1). promote =
["ALL"] escalates every advisory at once. A code in promote must be one a
loaded check declares, so load the plugin in the same run; otherwise the run
exits 2 with 'promote' names no known rule code or category.
A rule that asks a question about a design choice rather than reporting a
defect can stay advisory under ALL (and so under the strict profile).
Declare its code in an advisory_codes class attribute; only a promote entry
naming the code or its category escalates it then:
from typing import ClassVar
class HouseRulesCheck:
advisory_codes: ClassVar[frozenset[str]] = frozenset({"HOUSE-001"})
Loading the plugin¶
LaNorme has three ways to load a plugin module so its register() call runs.
Choose one.
Name it in config¶
List the module under plugins in [tool.lanorme]. LaNorme imports each named
module before the run, so the check self-registers:
[tool.lanorme]
plugins = ["myproject.checks.house_rules"]
This is the usual choice for a check that lives in your own repository. The
plugins reference documents the key.
Ship it under the entry-point group¶
A distributable package can advertise its check module under the
lanorme.checks entry-point group. Any environment that installs the package
then has the check available with no per-project config:
# in the plugin package's pyproject.toml
[project.entry-points."lanorme.checks"]
house-rules = "myproject.checks.house_rules"
The entry-point value is the dotted module path; LaNorme imports it on every run.
Pass it on the command line¶
Use --plugin for a one-off run, a quick experiment, or CI wiring that prefers
explicit flags over config:
$ lanorme check src/ --plugin myproject.checks.house_rules
CLI flags override config, so --plugin adds to whatever plugins already
lists.
Configuring a check¶
To accept settings from a [tool.lanorme.<name>] table, implement an optional
configure method. LaNorme hands it the table (a dict) before the run.
Read each value through the typed readers in lanorme.checkconfig:
is_flag_set for a boolean, read_int, read_str and read_str_list. Each
returns the value or rejects the wrong type (a quoted number, a float or true
for an integer, a bare string for a list). Declare the keys configure reads
in settings_keys. LaNorme then refuses a key outside that set, and
--show-config lists the set on the check's keys: line. Both mistakes exit
2 and name the table and the key.
A reader rejects a value by raising lanorme.checkconfig.SettingError (a
TypeError), and a configure that validates a value itself raises
TypeError or ValueError; LaNorme reports any of these as a
ConfigError naming the table and, where it can isolate it, the key. Any
other exception out of configure (an AttributeError, a KeyError) is a
bug in the check and surfaces as one, not as the user's mistake.
# stray_extensions.py
from dataclasses import dataclass, field
from typing import ClassVar
from lanorme import CheckResult, Violation, register
from lanorme.checkconfig import is_flag_set, read_str_list
from lanorme.discovery import iter_files
from lanorme.scan import Scan
@dataclass
class StrayExtensions:
name: str = "stray_extensions"
description: str = "Flag unwanted file extensions in the tree"
enabled: bool = False
extensions: tuple[str, ...] = ()
rules: list[str] = field(default_factory=lambda: ["HOUSE-002: Unwanted file extension"])
settings_keys: ClassVar[frozenset[str]] = frozenset({"enabled", "extensions"})
def configure(self, *, settings: dict[str, object]) -> None:
self.enabled = is_flag_set(settings=settings, key="enabled", default=self.enabled)
self.extensions = read_str_list(
settings=settings, key="extensions", default=self.extensions
)
def check(self, scan: Scan) -> CheckResult:
if not self.enabled:
return CheckResult.from_findings(check=self.name)
root = scan.root
warnings = [
Violation(
file=path.relative_to(root).as_posix(),
line=0,
rule="HOUSE-002",
message=f"File with unwanted extension {suffix}",
fix="Delete it, or keep it out of the repository",
)
for suffix in self.extensions
for path in iter_files(root, suffix=suffix)
]
return CheckResult.from_findings(check=self.name, warnings=warnings)
register(StrayExtensions())
A user then configures it under the check's own table, named after self.name:
[tool.lanorme.stray_extensions]
enabled = true
extensions = [".zip", ".tmp"]
With stray_extensions.py importable and src/old.zip and src/notes.tmp in
the tree:
$ lanorme check . --plugin stray_extensions --check stray_extensions
[WARN] stray_extensions
WARNING: src/old.zip:0 — File with unwanted extension .zip
Rule: HOUSE-002: Unwanted file extension
Fix: Delete it, or keep it out of the repository
WARNING: src/notes.tmp:0 — File with unwanted extension .tmp
Rule: HOUSE-002: Unwanted file extension
Fix: Delete it, or keep it out of the repository
--- stray_extensions: 0 violations, 2 warnings ---
Summary: 1 checks — 0 passed, 1 warned, 0 failed.
Findings: 0 errors to fix, 2 advisory warnings.
A mistyped value or key stops the run before any check starts:
$ cat pyproject.toml
[tool.lanorme.stray_extensions]
enabled = true
extension = [".zip"]
$ lanorme check . --plugin stray_extensions
ERROR: unknown key in [tool.lanorme.stray_extensions]: 'extension'.
Keys this check reads: enabled, extensions.
$ echo $?
2
An opt-in check defaults enabled to false and returns an empty result
(CheckResult.from_findings(check=self.name)) until the table sets
enabled = true. That keeps a broad or opinionated rule inert on a project
that has not asked for it. The concise summary counts such checks on its
Opt-in checks not enabled: line, and --check on one prints a note saying
it is off.
When only some of a check's rules wait on a setting, declare them in a class
attribute opt_in_rules: frozenset[str] and, to name the setting, an
opt_in_settings: dict[str, str] from code to key. lanorme rule CODE then
reports the rule as opt-in via <key> = true in [tool.lanorme.<check>]
instead of on by default, as comments does for PROSE-001 (em_dash).
For a mistake configure cannot express as a type, such as two settings that
contradict each other, raise lanorme.errors.ConfigError with the key and
source it concerns. The CLI reports it the same way, with exit 2.
Verify it is loaded¶
Run the check and confirm it executed. --output-format full shows passing
checks too, so a loaded check appears even when it found nothing:
$ lanorme check . --plugin myproject.checks.house_rules --output-format full
For a check loaded via config or the entry-point group, drop the --plugin
flag: plain lanorme check . --output-format full lists it once it is
registered. Seeing your check in that output (a [PASS] line when it is clean)
is the reliable signal that the plugin loaded. For machine-readable output while
developing, use --output-format ndjson (one finding per line) or
--output-format json (one object per check).
lanorme rules is a narrower check. It lists only rules registered through the
lanorme.checks entry-point group, so it surfaces a plugin shipped that way but
not one loaded via [tool.lanorme] plugins or --plugin. The rules command
also takes no --plugin flag.
Related pages¶
- Configuration reference: every
[tool.lanorme]key, includingplugins,select,ignore, andpromote. - Rule reference: what each built-in rule catches and how to configure it; a model for documenting your own.