Configuration (jaxlint.toml / pyproject.toml)

Configuration (jaxlint.toml / pyproject.toml)#

jaxlint discovers optional settings by walking upward from a starting directory ([root] + root.parents):

  • the --config directory (CLI), when --config points at a directory;

  • the current working directory, when --config is omitted;

  • or only the --config file, when --config points at jaxlint.toml or pyproject.toml (no upward walk).

At each directory during the walk:

  1. If jaxlint.toml exists in that directory, parse configuration from it and stop (pyproject.toml in the same directory is not read).

  2. Else if pyproject.toml exists there, parse [tool.jaxlint] from it and stop.

  3. Else continue to the parent directory.

If both jaxlint.toml and pyproject.toml exist in the same directory, loading fails with ValueError (pick one file).

Section layout by file#

File

Sections

jaxlint.toml

Native [jaxlint] (recommended) or legacy [tool.jaxlint]. Do not use both in the same file — loading fails with a clear error.

pyproject.toml

[tool.jaxlint] only. A top-level [jaxlint] table is rejected — configure jaxlint under [tool.jaxlint] per PEP 621 tooling conventions.

Equivalent settings under [jaxlint] vs [tool.jaxlint] in jaxlint.toml produce the same parsed LintConfig (including disk cache fingerprints).

Parsed keys live in LintConfig (jaxlint.core.config). TOML keys use kebab-case; Python attributes use snake_case.

Keys#

TOML key

Type

Default

Meaning

select

list of strings

(empty)

If non-empty, only rules whose id matches any pattern (see below) run.

ignore

list of strings

(empty)

Rules matching any pattern are skipped after per-file rules.

docstring-style

string

"numpy"

Passed to the docstring style validator (Griffe-backed).

required-sections

list of strings

["Parameters", "Returns"]

Section titles required in public APIs (see JD002).

section-order

list of strings

Parameters, Returns, Raises, Examples, Pseudocode, Hardware Notes

Canonical order for JD003 warnings.

strict-shapes

bool

false

If true, JL005 is promoted to error severity.

rubric-threshold

float

0.75

Default threshold for jaxlint score.

cache-dir

string (path)

(unset)

Optional directory for caching jaxlint check diagnostics. Relative paths are resolved against the directory containing the loaded config file (jaxlint.toml or pyproject.toml). jaxlint check --cache-dir overrides this when the CLI flag is present.

severity-overrides

table

{}

Map rule-id patterns → error, warning, or info. Applied after sensors (including strict-shapes for JL005) and after select / ignore / per-file-ignores. Pattern matching uses the same rules as select / ignore (pattern_matches). Keys must match at least one known rule id (unknown keys are rejected at parse time). Invalid severity strings are rejected at parse time.

sarif-rule-docs-base

string (URL)

(unset)

When set, --format sarif includes a helpUri on each tool.driver.rules entry: the base URL (trailing / optional) plus / and the rule_id. Must be https://; empty strings and non-HTTPS URLs are rejected at parse time.

per-file-ignores

table

{}

Map of glob patterns → rule patterns to disable for matching paths.

select, ignore, and per-file-ignores patterns#

Matching is implemented by pattern_matches in jaxlint.core.config:

  • Exact: JL001 matches only JL001.

  • Prefix: a pattern ending with * matches rule ids that start with the prefix before *. Example: JL matches every id starting with JL; JL* does the same.

per-file-ignores keys are matched with fnmatch against the string form of the file path passed to rule_enabled (typically relative paths like tests/fixtures/foo.py). Values can be a single string or a list of strings; each entry uses the same pattern rules as ignore.

Examples#

Standalone config file (jaxlint.toml) — native table:

[jaxlint]
select = ["JD", "JM"]

Project manifest (pyproject.toml) — PEP 621 tool table:

[tool.jaxlint]
select = ["JD", "JM"]

Strict shape checks (JL005 as errors), native jaxlint.toml:

[jaxlint]
strict-shapes = true

Downgrade JL005 to a warning even when strict-shapes is true (override wins):

[jaxlint]
strict-shapes = true

[jaxlint.severity-overrides]
JL005 = "warning"

The same layout under [tool.jaxlint] / [tool.jaxlint.severity-overrides] remains valid in jaxlint.toml for backward compatibility.

Ignore JL005 everywhere except tune per directory:

[jaxlint]
ignore = ["JL005"]

[jaxlint.per-file-ignores]
"experimental/**" = ["JL012"]
"kernels/**/*.py" = ["JL005", "JL010"]

Custom section order for JD003:

[jaxlint]
section-order = ["Parameters", "Returns", "Examples", "Raises"]
Contents