Python API

PragyaLint is built as a library with a thin CLI on top. You can call the same pipeline directly — run an analysis, inspect the report, and apply fixes — without shelling out.

analyze()

from pragyalint.analyzer import analyze

report = analyze(root_dir=".", entry=["src/main.py"])

Full signature:

analyze(
    root_dir: str,
    entry: list[str] | None = None,
    ignore: list[str] | None = None,
    extensions: list[str] | None = None,
    include: list[str] | None = None,
    rules: list[str] | None = None,
    report_unused_exports: bool = True,
    conventional_entries: bool = True,
    include_entry_exports: bool = False,
    ignore_tests: bool = False,
    detect_cycles: bool = False,
    fail_on: str | None = None,
    include_deps: bool = False,
    hooks: dict | None = None,
) -> AnalysisReport

These mirror the CLI flags exactly (see CLI commands). entry/rules/hooks may be None for "auto"; passing hooks replaces the rule set — see Plugins.

AnalysisReport

report.to_dict() produces the same structure as pragyalint --json.

Finding

Finding(
    rule: str,                 # unused_file / unused_import / unused_export / unused_local / cycle
    confidence: str,           # "high" | "medium" | "low"
    message: str,
    file: str | None = None,
    line: int | None = None,
    column: int | None = None,
    extra: dict | None = None, # rule-specific metadata, e.g. the unused name
)

Confidence provides the constants (HIGH, MEDIUM, LOW) and parsers (parse(), parse_min()).

apply_fixes()

from pragyalint.fixer import apply_fixes

result = apply_fixes(
    report,
    targets=["files", "imports", "exports"],
    min_confidence="high",     # "high" | "medium" | "low" (from --confidence)
    dry_run=True,              # preview only
    force=False,               # allow unsafe edits
)

Returns a FixResult with three lists: applied, dry_run, and skipped. The same confidence gating and safety checks that protect the CLI apply here (see Fixes & --fix).

Reporters

from pragyalint.reporters import format_terminal, format_json, format_sarif

print(format_terminal(report))
print(format_json(report))
print(format_sarif(report))

Complete example

from pragyalint.analyzer import analyze
from pragyalint.fixer import apply_fixes

report = analyze(root_dir="src", detect_cycles=True)

for finding in report.findings:
    print(f"{finding.rule}	{finding.confidence}	{finding.line}	{finding.message}")

# Preview fixing dead imports
result = apply_fixes(report, targets=["imports"], min_confidence="high", dry_run=True)
for planned in result.dry_run:
    print("would:", planned)