Metadata-Version: 2.4
Name: ast-metrics
Version: 0.41.1
Summary: AST Metrics bridge for Python: multi-language maintainability metrics, installable with pip and runnable with pipx
Author-email: Jean-François Lépine <lepinejeanfrancois@gmail.com>
License: MIT
Project-URL: Homepage, https://ast-metrics.dev
Project-URL: Repository, https://github.com/ast-metrics/ast-metrics-bridge-python
Project-URL: Issues, https://github.com/ast-metrics/ast-metrics-bridge-python/issues
Project-URL: Analyzer, https://github.com/ast-metrics/ast-metrics
Keywords: static analysis,metrics,complexity,maintainability,quality,python,code-quality,cyclomatic-complexity,technical-debt,pre-commit
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# AST Metrics for Python

[AST Metrics](https://github.com/ast-metrics/ast-metrics) is a static analyzer
that tells you which parts of a codebase are risky to touch. This package
installs it with pip, like any other dev tool: no compiler, no service. The
analyzer is a single binary, downloaded once and cached.

> **You may not need this package.** It exists for one thing: getting the
> analyzer through pip, so it lands in `requirements.txt` (or `uv.lock`) with
> the rest of your tooling and `pipx run ast-metrics` just works. If that is
> not what you are after, install the analyzer directly:
>
> ```bash
> brew install ast-metrics/tap/ast-metrics    # macOS, Linux
> curl -fsSL https://install.ast-metrics.dev | sh
> ```
>
> And on pull requests, there is a ready-made action:
> [`ast-metrics/action-ast-metrics@v2`](https://github.com/ast-metrics/action-ast-metrics).

## Usage

Without installing anything:

```bash
pipx run ast-metrics analyze src
```

Or as a dev dependency, which pins the analyzer version in your lockfile:

```bash
pip install ast-metrics          # add it to requirements-dev.txt yourself
# or, with uv:
uv add --dev ast-metrics

ast-metrics analyze src
ast-metrics analyze --report-html=./report src
```

If the virtualenv's `bin` (or `Scripts`) directory is not on `PATH`, run it as
a module instead: `python -m ast_metrics analyze src`. It behaves exactly like
the `ast-metrics` command.

Everything else: `ast-metrics --help`, or
[ast-metrics.dev](https://ast-metrics.dev).

## What gets analyzed

Python (`.py`), and, in the same run, `Go`, `PHP`, `TypeScript`, `Rust`,
`Java` and `C#`. Most codebases are not made of one language, and the metrics
are comparable across all of them.

## In CI

```yaml
- run: pipx run ast-metrics analyze --ci src
```

`--ci` writes the HTML and Markdown reports and keeps the output plain.
Reports for a quality gate: `--report-sarif=<file>` (read by GitHub code
scanning and GitLab), `--report-json=<file>`, `--report-openmetrics=<file>`.

The binary is downloaded once per version and cached in
`$AST_METRICS_CACHE_DIR`, which defaults to `$XDG_CACHE_HOME/ast-metrics` or
`~/.cache/ast-metrics`, so caching that directory between builds removes the
download entirely.

## Pre-commit hook

This repository ships a [`.pre-commit-hooks.yaml`](.pre-commit-hooks.yaml):

```yaml
repos:
  - repo: https://github.com/ast-metrics/ast-metrics-bridge-python
    rev: v0.41.1
    hooks:
      - id: ast-metrics
```

Without a `.ast-metrics.yaml` configuration file that sets requirements,
`ast-metrics lint` has nothing to check and does nothing. Run `ast-metrics
init` once to create one.

## Configuration

All optional.

| Variable | Effect |
| --- | --- |
| `AST_METRICS_BINARY` | Path to a binary to use as-is, nothing downloaded: air-gapped installs, distribution packages. |
| `AST_METRICS_VERSION` | Release tag to download, or `latest`. Defaults to the pinned version. |
| `AST_METRICS_CACHE_DIR` | Where binaries are cached. Defaults to `$XDG_CACHE_HOME/ast-metrics`, or `~/.cache/ast-metrics` if unset (`%LOCALAPPDATA%\ast-metrics` on Windows). |
| `HTTP_PROXY`, `HTTPS_PROXY`, `NO_PROXY` | Honoured for the download by `urllib`, the standard-library HTTP client this package uses. |

The analyzer version is pinned by this package rather than resolved to
`latest`, so a locked `requirements.txt` (or `uv.lock`) gives a reproducible
analysis. The package version matches the analyzer version it installs:
`ast-metrics==0.41.1` runs AST Metrics 0.41.1. To upgrade, `pip install
--upgrade ast-metrics` or `uv lock --upgrade-package ast-metrics`.

Unlike npm, pip has no post-install hook: nothing is downloaded at `pip
install` time. The binary is fetched on the first run of `ast-metrics` (or
`python -m ast_metrics`), then cached for every run after that. On an
air-gapped or hermetic install, where that first run cannot reach the
network, install the binary yourself and set
`AST_METRICS_BINARY=/path/to/ast-metrics` before running this package.

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Analyzer bugs go to
[ast-metrics/ast-metrics](https://github.com/ast-metrics/ast-metrics); this
repository is the Python bridge.

## License

MIT. See [LICENSE](LICENSE).
