Sanopy

Sanopy is a CLI tool for improving Python code quality. It runs multiple linters concurrently and emits findings as JSON to stdout.

Requirements

• Python 3.12+
• uv

Installation

pip install sanopy

# Optional with uv
uv venv .venv
uv pip install sanopy

Quick Start

1. Configure

Sanopy always uses a local .sanopy.toml in the current project.

• If .sanopy.toml does not exist, Sanopy creates it automatically with defaults.
• Use init to customize settings manually or in automation.

# Interactive (manual)
sanopy init

# Non-interactive (CI/automation)
sanopy init --only ruff,mypy --skip bandit

2. Scan a Codebase

sanopy scan src/

By default, machine-readable JSON is printed to stdout in a versioned envelope:

{
  "schema_version": "1.0.0",
  "run": {
    "target": "src",
    "generated_at": "2026-08-09T00:00:00+00:00",
    "active_linters": ["ruff", "pylint", "mypy"],
    "finding_count": 0
  },
  "findings": []
}

Use human output mode for terminal-friendly progress and summaries:

sanopy scan src/ --output-mode human

You can scan multiple directories or files at once:

sanopy scan src/ tests/

When scanning multiple targets, the results are merged into a single JSON document, and run.target becomes an array of the scanned paths.

Generate a human-readable Markdown report:

sanopy scan src/ --human-readable

The report is saved as linting-report-<target>.md (e.g., linting-report-src.md).

Save results to a custom file:

sanopy scan src/ -o my-scan.json

Linter Filtering

Run only selected linters:

sanopy scan . --only ruff,mypy

Skip selected linters:

sanopy scan . --skip safety

You can also set default only_linters and skip_linters values in .sanopy.toml via sanopy init.

Supported Linters

Configuration File

The .sanopy.toml file controls linter defaults for the current project.

• Manual workflow: run sanopy init and answer prompts.
• CI/AI workflow: run sanopy init --only ... --skip ... in scripts.
• If the file is missing, Sanopy creates .sanopy.toml with defaults.

[linters]
only_linters = []
skip_linters = []

[linters.pylint]
disable = ["duplicate-code", "too-many-locals"]

[linters.bandit]
skips = []

[linters.ruff]
select = ["E", "F", "W", "I", "N", "UP", "B", "A", "C4", "SIM", "PTH"]
ignore = []

[safety]
ignore_cves = ["CVE-2026-0994"]

[pip-audit]
ignore_vulns = ["PYSEC-2026-3482"]

The [safety] section lists CVE IDs that the Safety linter should suppress. By default a small set of known-unresolvable CVEs is ignored; set ignore_cves = [] to disable all suppressions.

The [pip-audit] section lists vulnerability IDs (or aliases) that the pip-audit linter should suppress, matched by primary ID or alias.

The optional [linters.<name>] sections provide the configuration that Sanopy passes to linters shipping bundled defaults (pylint, bandit, and ruff). A nested [linters.<name>.test] table overrides the settings used for test code. Sections and keys you omit fall back to the bundled defaults; a freshly generated .sanopy.toml materializes all of them so they are visible and editable.

Example CI step:

steps:
  - name: Configure Sanopy
    run: sanopy init --only ruff,mypy --skip bandit
  - name: Run scan
    run: sanopy scan src/ tests/

Development

Clone the repo and install dependencies:

git clone https://github.com/lpozo/sanopy.git
cd sanopy
uv sync

Run tests:

uv run pytest