Configure which checks run¶
This how-to gives recipes for narrowing what LaNorme runs and silencing the
noise you have decided to accept, from selecting a subset of rules down to
silencing a single line. Each recipe gives the goal, the [tool.lanorme]
config, the equivalent command-line flag where one exists, and a verified
example.
A finding has to survive every stage below to be reported, applied in this order:
flowchart LR
A[select] --> B[ignore]
B --> C[exclude]
C --> D[per-file-ignores]
D --> E[inline ignore]
E --> F[reported]
Config is read from [tool.lanorme] in pyproject.toml, or from a
lanorme.toml / .lanorme.toml file. LaNorme walks up from the scan path to
the outermost config, and a nested config cascades over the ones above it; see
config discovery. Command-line flags
override config for a single run. For the full key list and types, see the
configuration reference. Rule codes and
categories are listed by lanorme rules; per-check settings live in the
rule reference.
Note
The recipes below use the pyproject.toml layout. In a standalone
lanorme.toml / .lanorme.toml the tool.lanorme prefix is dropped:
top-level scalar keys go bare (select = [...]) and sub-tables lose the
prefix too, so [tool.lanorme.per-file-ignores] becomes
[per-file-ignores]. A prefixed header in a lanorme.toml is a
configuration error (exit 2), as is any top-level key that is neither a
run key nor the name of a check. See the
config discovery note in the CLI
reference.
Targets are rule codes (EVAL-001), categories (the part before the dash:
CMT, SECRETPY), or ALL. lanorme rules lists every code. A target that
names no known code or category, in a flag, in [tool.lanorme] or in
per-file-ignores, is a usage error: the run exits 2 and points you at
lanorme rules.
$ lanorme check src --select EVAL-01
ERROR: 'select' names no known rule code or category: 'EVAL-01'.
Run 'lanorme rules' to list every code and category.
$ echo $?
2
Run only some checks¶
Goal: run a chosen subset and skip everything else.
[tool.lanorme]
select = ["SECRETPY", "EVAL-001"]
Equivalent flag: --select takes a comma-separated list.
$ lanorme check src --select EVAL-001
[FAIL] security_calls
VIOLATION: pkg/main.py:1 — eval() on a non-literal argument is an RCE primitive
Rule: EVAL-001: No eval/exec/compile on a non-literal argument
Fix: Use ast.literal_eval for trusted-shape parsing, or build a dispatch table
--- security_calls: 1 violations, 0 warnings ---
Summary: 31 checks — 30 passed, 0 warned, 1 failed.
Findings: 1 error to fix, 0 advisory warnings.
Opt-in checks not enabled: 12 ('lanorme check --show-config' lists them).
A category selects every code under it: --select CMT runs every comment
rule; --select ALL runs everything enabled. --select takes codes and
categories, not check names. To run one check by name, use --check
(--check file_limits).
Note
Opt-in checks stay off even when named in select. Enable them first
with [tool.lanorme.<check>] enabled = true (for example
[tool.lanorme.prose]). See the rule reference.
Skip a rule everywhere¶
Goal: keep the full run but drop one rule (or one category) you do not want.
[tool.lanorme]
ignore = ["PARAM-001"]
Equivalent flag: --ignore takes a comma-separated list. Here the
file_limits check finds a nine-parameter function:
$ lanorme check src --check file_limits
[FAIL] file_limits
VIOLATION: pkg/wide.py:1 — Function 'build' has parameter count 9 (limit: 8)
Rule: PARAM-001: Function exceeds the parameter limit
Fix: Group related parameters into a dataclass or TypedDict
--- file_limits: 1 violations, 0 warnings ---
Summary: 1 checks — 0 passed, 0 warned, 1 failed.
Findings: 1 error to fix, 0 advisory warnings.
Ignoring PARAM-001 drops it and keeps the rest of the check:
$ lanorme check src --check file_limits --ignore PARAM-001
All 1 checks passed.
--select SIZE,COMPLEXITY narrows a full run to the size and complexity
codes the same way, leaving PARAM out.
ignore applies after select, so a rule that is both selected and ignored
is skipped.
Exclude paths from the scan¶
Goal: never walk certain files, such as generated code or migrations.
[tool.lanorme]
exclude = ["**/migrations/*", "generated/*"]
Equivalent flag: --exclude takes a comma-separated list of globs.
Globs match the path relative to the project root. A leading **/ matches a
directory at any depth, so **/migrations/* excludes src/pkg/migrations/:
$ lanorme check . --select EVAL-001
[FAIL] security_calls
VIOLATION: src/pkg/main.py:1 — eval() on a non-literal argument is an RCE primitive
Rule: EVAL-001: No eval/exec/compile on a non-literal argument
Fix: Use ast.literal_eval for trusted-shape parsing, or build a dispatch table
VIOLATION: src/pkg/migrations/m.py:1 — eval() on a non-literal argument is an RCE primitive
Rule: EVAL-001: No eval/exec/compile on a non-literal argument
Fix: Use ast.literal_eval for trusted-shape parsing, or build a dispatch table
--- security_calls: 2 violations, 0 warnings ---
Summary: 31 checks — 30 passed, 0 warned, 1 failed.
Findings: 2 errors to fix, 0 advisory warnings.
Opt-in checks not enabled: 12 ('lanorme check --show-config' lists them).
$ lanorme check . --select EVAL-001 --exclude '**/migrations/*'
[FAIL] security_calls
VIOLATION: src/pkg/main.py:1 — eval() on a non-literal argument is an RCE primitive
Rule: EVAL-001: No eval/exec/compile on a non-literal argument
Fix: Use ast.literal_eval for trusted-shape parsing, or build a dispatch table
--- security_calls: 1 violations, 0 warnings ---
Summary: 31 checks — 30 passed, 0 warned, 1 failed.
Findings: 1 error to fix, 0 advisory warnings.
Opt-in checks not enabled: 12 ('lanorme check --show-config' lists them).
Match the depth you have. To exclude a migrations/ directory sitting at the
project root, use migrations/*; the leading **/ form needs a parent
segment and will not match a top-level directory.
Naming an excluded path on the command line does not override the glob. With
exclude = ["**/migrations/*"] in config, asking for the excluded file checks
nothing: the run reports a clean tree and a note on stderr says so.
$ lanorme check src/pkg/migrations/m.py --select EVAL-001
Note: every requested path matches an exclude glob, so nothing was checked. Pass --exclude with another glob to override the configured excludes for one run.
All 31 checks passed.
Opt-in checks not enabled: 12 ('lanorme check --show-config' lists them).
Silence a rule for a path glob¶
Goal: keep a rule on, but accept it for files matching a glob (for example,
allow wide-signature test factories under tests/ to keep PARAM-001).
This is config only; there is no command-line equivalent.
Without any suppression, a nine-parameter factory in tests/factories.py
reports PARAM-001:
$ lanorme check . --select PARAM-001
[FAIL] file_limits
VIOLATION: tests/factories.py:1 — Function 'build' has parameter count 9 (limit: 8)
Rule: PARAM-001: Function exceeds the parameter limit
Fix: Group related parameters into a dataclass or TypedDict
--- file_limits: 1 violations, 0 warnings ---
Summary: 31 checks — 30 passed, 0 warned, 1 failed.
Findings: 1 error to fix, 0 advisory warnings.
Opt-in checks not enabled: 12 ('lanorme check --show-config' lists them).
The key is a glob; the value is a list of codes or categories suppressed for
matching files. In pyproject.toml the table carries the tool.lanorme
prefix:
[tool.lanorme.per-file-ignores]
"tests/*" = ["PARAM-001"]
In a standalone lanorme.toml / .lanorme.toml the prefix is dropped and the
header is bare. The prefixed form is silently ignored there:
[per-file-ignores]
"tests/*" = ["PARAM-001"]
With either form in place, the matching file is no longer reported, and the summary counts what the glob suppressed:
$ lanorme check . --select PARAM-001
All 31 checks passed.
Suppressed: 0 by inline ignores, 1 by per-file-ignores, 0 by the baseline.
Opt-in checks not enabled: 12 ('lanorme check --show-config' lists them).
Globs match paths relative to the project root, and so does a nested region:
a tests/lanorme.toml does not change what "tests/*" matches.
Confirm the discovered config and effective per-check settings with
lanorme check --show-config.
Silence one line¶
Goal: accept a single finding in place, at the source line.
This is a source pragma; there is no command-line equivalent. Two directives are read, both on the finding's own line:
# noqasuppresses every finding on that line.# noqa: CODEsuppresses only that rule code on that line; other findings on the line still report, and a different code does not suppress.# lanorme: ignoreand# lanorme: ignore[CODE, CODE]behave the same way, bare or with a bracketed code list.
# noqa is shared with ruff and other linters, so a bare # noqa you add for
ruff also silences LaNorme on that line. Reach for # lanorme: ignore[...]
when you run both tools and want to silence a LaNorme finding alone: ruff
cannot parse the hyphen in a code like TYPE-001, so a shared # noqa:
TYPE-001 makes ruff report an invalid directive, while # lanorme: ignore
carries no noqa token for ruff to read.
A code in either directive may be an exact code (EVAL-001), a category
(CMT), or ALL, matching the other config targets. A finding reported at
line 0 is about the whole file (a junk-drawer module, say) and has no line
to carry a directive; silence it with per-file-ignores instead.
Given this file checked with --select EVAL-001:
def f():
x = eval(input())
def g():
y = eval(input()) # noqa
def h():
z = eval(input()) # noqa: EVAL-001
def k():
w = eval(input()) # lanorme: ignore[EVAL-001]
def m():
v = eval(input()) # noqa: SQL-001
Only lines 2 and 18 are reported. The bare # noqa, the matching
# noqa: EVAL-001 and # lanorme: ignore[EVAL-001] suppress their lines.
# noqa: SQL-001 names the wrong code and does not silence the eval.
$ lanorme check a.py --select EVAL-001
[FAIL] security_calls
VIOLATION: a.py:2 — eval() on a non-literal argument is an RCE primitive
Rule: EVAL-001: No eval/exec/compile on a non-literal argument
Fix: Use ast.literal_eval for trusted-shape parsing, or build a dispatch table
VIOLATION: a.py:18 — eval() on a non-literal argument is an RCE primitive
Rule: EVAL-001: No eval/exec/compile on a non-literal argument
Fix: Use ast.literal_eval for trusted-shape parsing, or build a dispatch table
--- security_calls: 2 violations, 0 warnings ---
Summary: 31 checks — 30 passed, 0 warned, 1 failed.
Findings: 2 errors to fix, 0 advisory warnings.
Suppressed: 3 by inline ignores, 0 by per-file-ignores, 0 by the baseline.
Opt-in checks not enabled: 12 ('lanorme check --show-config' lists them).
Tune a check's settings¶
Goal: change a check's threshold or option, such as the parameter limit.
Each check reads its own table, named after the check. The keys it accepts are in its rule reference section.
[tool.lanorme.file_limits]
param_error = 10
With the limit raised to 10, the nine-parameter factory drops from an error to
an advisory warning (it is still past the warning threshold of 5), and the run
exits 0.
Every table is validated before the run. A value of the wrong type exits 2
and names the table and the key. That covers a quoted number, a bare string
where a list is expected, and a float or true where an integer is expected:
$ cat pyproject.toml
[tool.lanorme.file_limits]
param_error = "10"
$ lanorme check . --select PARAM-001
ERROR: invalid value for [tool.lanorme.file_limits] param_error: 'param_error' must be an integer, got str
Run 'lanorme check . --show-config' to see the effective settings for every check.
A key the check does not read also exits 2, and the message lists the keys
it does read:
$ cat pyproject.toml
[tool.lanorme.file_limits]
param_limit = 10
$ lanorme check . --select PARAM-001
ERROR: unknown key in [tool.lanorme.file_limits]: 'param_limit'.
Keys this check reads: class_method_warn, complexity_error, complexity_warn, file_error_lines, file_warn_lines, func_error_lines, func_warn_lines, param_error, param_warn.
The top level is strict in the same way: a key that is neither a run key
(select, promote, source_root, ...) nor the name of a check exits 2
and lists both, and a [tool.lanorme] table inside a lanorme.toml is
refused with a message saying the keys go top level there. See
config discovery.
lanorme check --show-config prints each check's effective settings and,
on a keys: line under it, the keys its table accepts:
$ lanorme check . --show-config
...
file_limits file_warn_lines=300 file_error_lines=500 func_warn_lines=50 func_error_lines=80 class_method_warn=10 complexity_warn=10 complexity_error=15 param_warn=5 param_error=10
keys: class_method_warn, complexity_error, complexity_warn, file_error_lines, file_warn_lines, func_error_lines, func_warn_lines, param_error, param_warn
...
Exit codes¶
lanorme check exits 0 when clean or when only warnings were found, 1
when there are violations, and 2 on a usage or config error. This drives
CI: a silenced finding leaves the run clean.
$ lanorme check src --select EVAL-001 # no eval in src
All 31 checks passed.
Opt-in checks not enabled: 12 ('lanorme check --show-config' lists them).
$ echo $?
0
See also¶
- Configuration reference for every
[tool.lanorme]key, includingpromote,extends,baseline,source_root, andplugins. - Rule reference for what each code catches and its per-check settings.