Python API reference

Stable entry points for embedding jaxlint. These pages use autodoc and a compact autosummary index of jaxlint.core re-exports.

jaxlint.core does not import JAX. Optional jaxlint[hlo] is documented narratively in HLO extra (jaxlint[hlo]); API HTML for jaxlint.hlo is not built here so doc builds stay free of the JAX stack.

jaxlint.core summary

Diagnostic	Diagnostic(rule_id: 'str', severity: 'Severity', message: 'str', path: 'Path', line: 'int', col: 'int' = 0, end_line: 'int | None' = None, end_col: 'int | None' = None)
Severity
RULES	Built-in mutable sequence.
describe_rules
resolve_paths
run_checks
format_compact	One line per diagnostic: path:line:col: severity: message (rule_id).
format_text
format_json
format_github_annotations_json	JSON shaped for GitHub Checks output.annotations (REST API field names).
format_sarif	Minimal SARIF 2.1.0 log (best-effort for generic viewers; not GHAS-specific).
format_diagnostics	Format diagnostics for CLI / library use.

Public core API surface.

class jaxlint.core.Diagnostic(rule_id: 'str', severity: 'Severity', message: 'str', path: 'Path', line: 'int', col: 'int' = 0, end_line: 'int | None' = None, end_col: 'int | None' = None)

Bases: object

rule_id: str

severity: Severity

message: str

path: Path

line: int

col: int

end_line: int | None

end_col: int | None

sort_key() → tuple

class jaxlint.core.Severity(*values)

Bases: str, Enum

ERROR = 'error'

WARNING = 'warning'

INFO = 'info'

jaxlint.core.describe_rules() → str

jaxlint.core.resolve_paths(paths: list[Path]) → list[Path]

jaxlint.core.run_checks(paths: list[Path], *, cfg: LintConfig | None = None, perf: bool = True, doc: bool = True, mathjx: bool = True, config_start: Path | None = None, jobs: int | None = None, cache_dir: Path | None = None) → list[Diagnostic]

jaxlint.core.diagnostics_for_python_source(path: Path, source: str, *, cfg: LintConfig | None = None, perf: bool = True, doc: bool = True, mathjx: bool = True, config_start: Path | None = None) → list[Diagnostic]

Lint in-memory Python source for path (unsaved buffers, LSP, etc.).

Semantics match _diagnostics_for_file() for the same path, flags, and config, but source is used instead of reading the file from disk. Results are sorted by Diagnostic.sort_key() (same contract as run_checks() for a single path).

The language server does not use the on-disk diagnostic cache (cache_dir); callers should omit caching for editor buffers.

jaxlint.core.format_compact(diagnostics: list[Diagnostic]) → str

One line per diagnostic: path:line:col: severity: message (rule_id).

jaxlint.core.format_text(diagnostics: list[Diagnostic]) → str

jaxlint.core.format_json(diagnostics: list[Diagnostic]) → str

jaxlint.core.format_github_annotations_json(diagnostics: list[Diagnostic]) → str

JSON shaped for GitHub Checks output.annotations (REST API field names).

Omits start_column / end_column when start_line != end_line (GitHub requires columns only for single-line annotations). Uses 1-based start_column / end_column; col / end_col of 0 are treated as start of line (column 1).

jaxlint.core.format_sarif(diagnostics: list[Diagnostic], *, tool_version: str, cfg: LintConfig | None = None) → str

Minimal SARIF 2.1.0 log (best-effort for generic viewers; not GHAS-specific).

jaxlint.core.format_rich(diagnostics: list[Diagnostic]) → str

Render diagnostics as a Rich panel + table (ASCII-safe when stdout is not a TTY).

jaxlint.core.format_diagnostics(diagnostics: list[Diagnostic], format_name: str, cfg: LintConfig | None = None) → str

Format diagnostics for CLI / library use.

cfg is used when format_name is SARIF — pass the same LintConfig as run_checks (or from load_config) so optional sarif-rule-docs-base can populate helpUri on rule descriptors.

Load lint settings from jaxlint.toml or pyproject.toml.

jaxlint.toml accepts a first-class [jaxlint] table or legacy [tool.jaxlint] (but not both). pyproject.toml must use [tool.jaxlint] only — a top-level [jaxlint] table is rejected.

class jaxlint.core.config.LintConfig(select: 'frozenset[str]' = frozenset(), ignore: 'frozenset[str]' = frozenset(), docstring_style: 'str' = 'numpy', required_sections: 'tuple[str, ...]' = ('Parameters', 'Returns'), section_order: 'tuple[str, ...]' = ('Parameters', 'Returns', 'Raises', 'Examples', 'Pseudocode', 'Hardware Notes'), strict_shapes: 'bool' = False, rubric_threshold: 'float' = 0.75, per_file_ignores: 'dict[str, tuple[str, ...]]' = <factory>, cache_dir: 'Path | None' = None, severity_overrides: 'dict[str, Severity]' = <factory>, sarif_rule_docs_base: 'str | None' = None)

Bases: object

select: frozenset[str] = frozenset({})

ignore: frozenset[str] = frozenset({})

docstring_style: str = 'numpy'

required_sections: tuple[str, ...] = ('Parameters', 'Returns')

section_order: tuple[str, ...] = ('Parameters', 'Returns', 'Raises', 'Examples', 'Pseudocode', 'Hardware Notes')

strict_shapes: bool = False

rubric_threshold: float = 0.75

per_file_ignores: dict[str, tuple[str, ...]]

cache_dir: Path | None = None

severity_overrides: dict[str, Severity]

sarif_rule_docs_base: str | None = None

classmethod default() → LintConfig

jaxlint.core.config.load_config(start: Path | None = None) → LintConfig

Load lint configuration from the discovery walk or a direct config file path.

jaxlint.toml may use native [jaxlint] or legacy [tool.jaxlint] (mutually exclusive). pyproject.toml only allows [tool.jaxlint].

• start is None — walk upward from the current working directory.

• start is a directory — walk upward from start.resolve() ([root] + root.parents).

• start is a file — parse jaxlint.toml or pyproject.toml at that path (no walk); relative TOML paths resolve against the directory containing the file.

jaxlint.core.config.pattern_matches(rule_id: str, pattern: str) → bool

jaxlint.core.config.effective_severity(d: Diagnostic, cfg: LintConfig) → Diagnostic

Apply severity-overrides so configured severity always wins (after rule selection).

jaxlint.core.config.rule_enabled(rule_id: str, cfg: LintConfig, file_path: Path) → bool

Apply select/ignore and per-file-ignores (glob patterns).

jaxlint.core.config.starter_toml_snippet() → str