API Reference¶

This reference documents all PSS AST classes generated by the pssparser. Classes are organized by category for easy navigation.

Checker Plug-in API ¶

These classes form the public API for writing and registering pssparser checker plug-ins. See Checker Plug-in Guide for a usage guide.

class pssparser.checkers.MarkerDef(id: str, severity: str, summary: str, detail: str = '')¶

Describes one diagnostic that a checker (or the core) may emit.

Attributes¶

id:: Globally unique identifier string, e.g. "PSS001" or "PSC042". IDs must be unique across all registered checkers and the core; the CheckerManager enforces this at discovery time.
severity:: Default severity: "error", "warning", "info", or "hint".
summary:: One-line description displayed in --list-markers output.
detail:: Multi-line explanation shown by --describe ID. May include reStructuredText markup.

detail: str = ''¶

id: str¶

severity: str¶

summary: str¶

class pssparser.checkers.CheckerBase¶

Abstract base for all pssparser plug-in checkers.

Subclasses must override name, description, marker_defs, and check().

check(context: CheckContext) → None¶

Perform checks and emit diagnostics via context.

Parameters¶

context:: Provides access to the AST and the marker-emission API.

description: str = ''¶: One-line description shown in --list-checkers.

marker_defs: List[MarkerDef] = []¶: Structured definitions of every marker this checker may emit. Each subclass must declare its own list — do not mutate the inherited one.

name: str = ''¶: Short unique identifier, e.g. "naming-convention".

runs_without_link: bool = False¶: If True the checker runs even when --syntax-only was requested (i.e. the linked AST is not available).

class pssparser.checkers.CheckContext(root: ~typing.Any | None, files: ~typing.List[str], global_scopes: ~typing.List[~typing.Any], file_map: ~typing.Dict[int, str] = <factory>, _markers: list = <factory>, _marker_index: ~typing.Dict[str, ~typing.Any] = <factory>)¶

Provides AST access and a diagnostic-emission API to checkers.

Attributes¶

root:: Fully-linked root symbol scope, or None when --syntax-only.
files:: Ordered list of source file paths that were parsed.
global_scopes:: Raw per-file GlobalScope AST nodes (same order as files).

add_marker(*, code: str, file: str, line: int, col: int, message: str, severity: str | None = None) → None¶

Emit one diagnostic from within a checker.

Parameters¶

code:: The MarkerDef.id for this diagnostic. Must be declared in the checker’s marker_defs list (enforced via _marker_index).
file:: Source file path.
line:: 1-based line number.
col:: 1-based column number.
message:: Human-readable diagnostic text.
severity:: Override the default severity declared in the MarkerDef. If omitted, the MarkerDef.severity is used.

Raises¶

ValueError: If code is not present in _marker_index.

file_map: Dict[int, str]¶: Maps fileid (int) -> source file path; allows checkers to resolve GlobalScope.getFileid() to a human-readable path when getFilename() is unavailable.

files: List[str]¶: Ordered list of source file paths that were parsed.

global_scopes: List[Any]¶: Raw per-file GlobalScope AST nodes (same order as files).

root: Any | None¶: Fully-linked root symbol scope, or None when –syntax-only.

class pssparser.checkers.CheckerManager¶

Manages discovery, filtering, and invocation of checker plug-ins.

Typical usage:

manager = CheckerManager()
manager.discover()                        # load entry_points
manager.load("mypkg.rules:MyChecker")     # optional: ad-hoc load
checkers = manager.active(select=None, exclude=["some-checker"])

active(select: List[str] | None, exclude: List[str] | None) → List[CheckerBase]¶

Return instantiated active checkers after applying filters.

is_builtin checkers are never included (they are metadata-only).

Parameters¶

select:: If non-empty, keep only these checker names. Unknown names raise ValueError (fail-fast).
exclude:: If select is None/empty and this is non-empty, remove these checker names from the active set. Unknown names are silently ignored.

Raises¶

ValueError: When select contains names not in the registry.

build_marker_index(active_checkers: List[CheckerBase]) → dict¶

Build a {marker_id: MarkerDef} index for the given checkers.

Always includes CoreChecker marker defs so that built-in codes can be looked up even though CoreChecker is not in active_checkers.

describe_marker(marker_id: str) → dict | None¶: Return a full description dict for marker_id, or None.

discover() → None¶

Register CoreChecker then all pssparser.checkers entry-points.

Idempotent: safe to call more than once, though once per process is the normal pattern (second call will raise on duplicate IDs if any entry-points were already registered).

list_all_markers() → List[dict]¶: Return every MarkerDef across all registered checkers.

list_checkers() → List[dict]¶: Return info dicts for --list-checkers display.

load(spec: str) → None¶

Load a checker from a 'module.path:ClassName' spec string.

Parameters¶

spec:: A string of the form "module.path:ClassName".

Raises¶

ValueError: On malformed spec, missing module/class, empty checker name, or duplicate marker IDs.