Metadata-Version: 2.4
Name: codepact
Version: 0.8.0
Summary: Lightweight Python contract annotations for CodePact
Author: CodePact contributors
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: typing-extensions>=4.7
Provides-Extra: cli
Requires-Dist: codepact-cli==0.8.0; extra == 'cli'
Description-Content-Type: text/markdown

# CodePact

![CodePact banner](https://raw.githubusercontent.com/eddiethedean/codepact/v0.8.0/docs/_static/codepact-banner.png)

CodePact finds Python resource bugs before runtime. Declare how an object
closes and which functions own or borrow it. CodePact reads source and can flag
a connection used after close, cleanup skipped on a supported exit, or a
discarded must-use result. Run it alongside your type checker and tests.

[![Quality](https://github.com/eddiethedean/codepact/actions/workflows/quality.yml/badge.svg?branch=main)](https://github.com/eddiethedean/codepact/actions/workflows/quality.yml)
[![Docs](https://app.readthedocs.org/projects/codepact/badge/?version=latest)](https://codepact.readthedocs.io/en/latest/index.html)
[![PyPI helper](https://img.shields.io/pypi/v/codepact?label=PyPI%20helper)](https://pypi.org/project/codepact/)
[![PyPI CLI](https://img.shields.io/pypi/v/codepact-cli?label=PyPI%20CLI)](https://pypi.org/project/codepact-cli/)
[![MIT license](https://img.shields.io/badge/License-MIT-blue)](https://github.com/eddiethedean/codepact/blob/main/LICENSE)

[Documentation](https://codepact.readthedocs.io/en/latest/index.html) ·
[Install options](https://codepact.readthedocs.io/en/latest/install.html) ·
[Rule catalog](https://codepact.readthedocs.io/en/latest/rules.html) ·
[Roadmap](https://github.com/eddiethedean/codepact/blob/main/ROADMAP.md)

**New in 0.8.0.** Check resource contracts across installed Python packages,
export and verify wheel contract manifests, and supply reviewed models for an
exact dependency version. Opt in to models for local text files, asyncio task
lifetimes, and multiprocessing with an explicit spawn context.
[Release notes](https://codepact.readthedocs.io/en/latest/release-notes.html) ·
[Reviewed contracts and runtime models](https://codepact.readthedocs.io/en/latest/reviewed-contracts.html)

## Quick start

In an empty directory with [uv](https://docs.astral.sh/uv/getting-started/installation/)
and Python 3.11 or later, start a project.

```sh
uv init --bare --name codepact-demo
uv add 'codepact[cli]==0.8.0'
uv run --locked codepact --version
mkdir src
```

Expect `codepact 0.8.0`.

Save the complete [connection example](https://github.com/eddiethedean/codepact/blob/v0.8.0/examples/lifecycle.py)
as `src/connection.py` and run the check.

```sh
uv run --locked codepact check --root src
```

Expect exit `1` with a related location pointing to the close.

```text
connection.py:23:1: error TP1001: Borrowed call requires an open resource
  related: connection.py:22:1
```

Delete the final line and rerun with `--mode strict` to confirm exit `0`.
[Full walkthrough](https://codepact.readthedocs.io/en/latest/quickstart.html) ·
[Install with pip or run the standalone command](https://codepact.readthedocs.io/en/latest/install.html)

## What you can check

| Declare | CodePact checks |
| --- | --- |
| `@resource(closed_by="close")` | Supported use after close and conflicting lifecycle metadata |
| `Owned[T]` | Cleanup duties across modeled exits and open resources at ownership handoff |
| `Borrowed[T]` | Closing a resource through a shared view |
| `@must_use` or `MustUse[T]` | Bare discarded calls to marked synchronous functions |

The helpers use `typing.Annotated`, so ordinary types remain available to mypy
and Pyright. The checker follows supported branches, aliases, calls, exceptions,
and cleanup paths. Check reports include primary and related source locations,
certainty, and coverage. [Contract syntax](https://codepact.readthedocs.io/en/latest/contracts.html) ·
[Supported syntax](https://codepact.readthedocs.io/en/latest/supported-syntax.html)

## Try experimental ownership

Add the following to `pyproject.toml` to enable move and lexical borrow checks.

```toml
[tool.codepact]
config-version = 1
experimental-ownership = true
```

Use `move(value)` to transfer a tracked handle and its cleanup duty. The
checker reports later use of the old handle. The TaskGroup model requires a
separate default-task-factory assumption.
[Ownership examples and scope](https://codepact.readthedocs.io/en/latest/ownership.html)

The new runtime models require an explicit profile for CPython 3.13.16 on
Linux x86-64. The profile describes the program you analyze. You can run the
checker on any supported CLI platform.
[Configure a runtime profile](https://codepact.readthedocs.io/en/latest/reviewed-contracts.html#select-the-runtime-profile)

## Run in CI

Start with a narrow source root. Use strict mode when incomplete coverage
should fail the job, and retain the JSON report alongside the exit status.

```sh
uv run --locked codepact check --root src --mode strict --json > codepact-report.json
```

| Exit | Meaning |
| --- | --- |
| `0` | The completed report passed the selected policy |
| `1` | The completed report failed policy |
| `2` | The invocation or check failed |

Advisory mode can pass with incomplete coverage. The coverage field describes
which parts of the program the checker could analyze. Teams can configure rule
severity, review a baseline, and record line-level exceptions with a reason.
Checks with installed dependency roots or a runtime profile emit report schema
4 with provider selection and model applicability details.
[Adoption guide](https://codepact.readthedocs.io/en/latest/adopting.html) ·
[CI workflow](https://codepact.readthedocs.io/en/latest/automation.html)

## Compatibility

The helper package runs on Python 3.11 and later, with CI on CPython 3.11–3.14.
The analyzer supports Python **3.11–3.13 source targets**. Native CLI wheels are
available for Linux, macOS, and Windows on x86-64 and ARM64. Building from
source requires Rust 1.96 or later and a linker.
[Platform matrix](https://codepact.readthedocs.io/en/latest/availability.html) ·
[Standalone CLI and Rust library](https://codepact.readthedocs.io/en/latest/install.html)

## Contribute

Run `uv sync --locked --extra cli` and `uv run --locked make check` after installing the
repository's pinned Cargo audit tools. The contributor guide lists the setup
and focused check targets.
[Contributing](https://github.com/eddiethedean/codepact/blob/main/CONTRIBUTING.md) ·
[Build the docs](https://codepact.readthedocs.io/en/latest/documentation.html) ·
[MIT license](https://github.com/eddiethedean/codepact/blob/main/LICENSE)
