Metadata-Version: 2.4
Name: python-checkup
Version: 0.1.1
Summary: Fast, local-first CLI that gives your Python codebase a 0-100 health score
Project-URL: Homepage, https://github.com/nabroleonx/python-checkup
Project-URL: Documentation, https://nabroleonx.github.io/python-checkup/
Project-URL: Repository, https://github.com/nabroleonx/python-checkup.git
Project-URL: Issues, https://github.com/nabroleonx/python-checkup/issues
Author: Abel Ayalew | @nabroleonx
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agent,code-quality,health-check,linting,mcp,python,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: bandit>=1.8
Requires-Dist: click>=8.1
Requires-Dist: deptry>=0.14
Requires-Dist: mypy>=1.13
Requires-Dist: radon>=6.0
Requires-Dist: rich>=13.0
Requires-Dist: ruff>=0.8.0
Requires-Dist: vulture>=2.12
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.14; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: basedpyright>=1.38; extra == 'full'
Requires-Dist: detect-secrets>=1.5; extra == 'full'
Requires-Dist: httpx>=0.27; extra == 'full'
Requires-Dist: mcp>=1.0; extra == 'full'
Requires-Dist: typos>=1.44; extra == 'full'
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == 'mcp'
Provides-Extra: pyright
Requires-Dist: basedpyright>=1.38; extra == 'pyright'
Provides-Extra: quality-extra
Requires-Dist: typos>=1.44; extra == 'quality-extra'
Provides-Extra: secrets
Requires-Dist: detect-secrets>=1.5; extra == 'secrets'
Provides-Extra: vulns
Requires-Dist: httpx>=0.27; extra == 'vulns'
Description-Content-Type: text/markdown

# python-checkup

Fast, local-first Python code health checks with a single command.

A 0-100 health score for Python codebases. Runs Ruff, mypy, Bandit, Radon,
Vulture, and deptry in parallel, scores six categories, and tells you what to
fix first.

![python-checkup overview](https://raw.githubusercontent.com/nabroleonx/python-checkup/main/docs/assets/overview.png)

## Quickstart

```bash
uvx python-checkup .
```

To see the full report in your browser:

```bash
uvx python-checkup . --web
```

To install persistently:

```bash
uv tool install python-checkup
```

## Usage

```bash
# quick scan (Ruff + deptry only, ~3s)
uvx python-checkup . --profile quick

# full scan with all optional analyzers
uvx --from 'python-checkup[full]' python-checkup .

# only changed files vs a branch
uvx python-checkup . --diff main

# auto-fix what Ruff can, then rescan
uvx python-checkup . --fix

# filter categories
uvx python-checkup . --only quality,security
uvx python-checkup . --skip dead_code

# output formats
uvx python-checkup . --score          # just the number
uvx python-checkup . --json           # machine-readable
uvx python-checkup . --badge          # shields.io URL

# CI gate
uvx python-checkup . --fail-under 70
```

## What it runs

**Default profile:**

| Category | Tools |
|---|---|
| Code Quality | Ruff |
| Type Safety | mypy |
| Security | Bandit, Ruff S-rules |
| Complexity | Radon, Ruff C901 |
| Dead Code | Vulture |
| Dependencies | deptry |

**Optional analyzers** (install via extras):

| Extra | Adds |
|---|---|
| `vulns` | OSV-backed dependency vulnerability scanning |
| `secrets` | detect-secrets |
| `pyright` | basedpyright as type backend |
| `quality-extra` | typos for spelling checks |
| `mcp` | MCP server support |
| `full` | all of the above |

## Scoring

Each category gets a 0-100 score. The overall score is a weighted average:

| Category | Default Weight |
|---|---|
| Code Quality | 25 |
| Type Safety | 20 |
| Security | 20 |
| Complexity | 15 |
| Dead Code | 10 |
| Dependencies | 10 |

When a category has no available analyzer, its weight redistributes
proportionally to the rest.

| Score | Label |
|---|---|
| 75-100 | Healthy |
| 50-74 | Needs work |
| 0-49 | Critical |

See `docs/scoring.md` for the full methodology.

## Configuration

Works without config. To customize, add to `pyproject.toml`:

```toml
[tool.python-checkup]
timeout = 60

[tool.python-checkup.weights]
quality = 25
types = 20
security = 20
complexity = 15
dead_code = 10
dependencies = 10

[tool.python-checkup.thresholds]
healthy = 75
needs_work = 50

[tool.python-checkup.ignore]
rules = ["S101"]
files = ["tests/**", "migrations/**"]
```

See `docs/configuration.md` for the full reference.

## CI

Gate on score:

```bash
uvx python-checkup . --fail-under 70
```

GitHub Action:

```yaml
- uses: nabroleonx/python-checkup@v1
  with:
    fail-under: 70
```

Also works as a pre-commit hook. See `action.yml` and `.pre-commit-hooks.yaml`.

## MCP Server

Expose python-checkup to AI coding agents (Claude Code, Cursor, VS Code):

```bash
uvx --from 'python-checkup[mcp]' python-checkup mcp install --editor cursor
```

Registers five tools: `python_checkup_diagnose`, `python_checkup_lint`,
`python_checkup_typecheck`, `python_checkup_security`, `python_checkup_explain_rule`.

See `docs/mcp-server.md` for details.

## Plugins

Add custom analyzers via entry points:

```toml
[project.entry-points."python-checkup.analyzers"]
my-analyzer = "my_package:MyAnalyzer"
```

See `docs/plugins.md` for the full guide.

## Docs

- `docs/configuration.md` -- weights, thresholds, ignore rules
- `docs/scoring.md` -- scoring methodology
- `docs/mcp-server.md` -- MCP server setup
- `docs/plugins.md` -- custom analyzer development
- `docs/development.md` -- contributing

## Development

```bash
uv sync --all-extras
uv run pytest
uv run ruff check python_checkup tests
uv run mypy python_checkup
```

## License

MIT
