Metadata-Version: 2.4
Name: codepact
Version: 0.9.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.9.0; extra == 'cli'
Description-Content-Type: text/markdown

# CodePact

![CodePact banner](https://raw.githubusercontent.com/eddiethedean/codepact/v0.9.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.9.0.** Track persistent outcome duties with `MustHandle`, require
declarations on selected APIs, and compare code changes or two published
wheels. Reviewed HTTP and SQL profiles add bounded client and session checks,
and work models track when a task or future result remains unobserved.
[Release notes](https://codepact.readthedocs.io/en/latest/release-notes.html) ·
[Review a change](https://codepact.readthedocs.io/en/latest/ci-reporting.html#review-a-change) ·
[Reviewed provider profiles](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.9.0'
uv run --locked codepact --version
mkdir src
```

Expect `codepact 0.9.0`.

Save the complete [connection example](https://github.com/eddiethedean/codepact/blob/v0.9.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 |
| `MustHandle[Result[T, E]]` or `MustHandle[Option[T]]` | Unacknowledged outcomes across supported assignments, aliases, and returns |

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)
