Skip to main content

CodePact

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 Docs PyPI helper PyPI CLI MIT license

Documentation · Install options · Rule catalog · Roadmap

Quick start

Use an empty directory with uv and Python 3.11 or later. This POSIX-shell example installs a pinned release, writes the sample, and checks it as source text. For the install pin that matches the current distribution, use the stable install guide.

uv init --bare --name codepact-demo
uv add 'codepact[cli]==0.9.0'
mkdir src
cat > src/connection.py <<'PYTHON'
"""Small lifecycle example with a borrowed use after close."""

from codepact import resource
from codepact.rust import Borrowed


@resource(closed_by="close")
class Connection:
    def status(self) -> str:
        return "ready"

    def close(self) -> None:
        pass


def inspect_connection(conn: Borrowed[Connection]) -> str:
    return conn.status()


conn = Connection()
inspect_connection(conn)
conn.close()
inspect_connection(conn)  # TP1001 at this call; close is the related location.
PYTHON
uv run --locked codepact check --root src

Expect exit 1 with TP1001 on the last call and a related location on the preceding close. Remove the last call and confirm the repair.

sed '$d' src/connection.py > connection-repaired.py
mv connection-repaired.py src/connection.py
uv run --locked codepact check --root src --mode strict
echo "$?"

Expect 0. Quick start with PowerShell instructions · Install with pip or use the standalone checker · Check whether your project fits

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 · Supported syntax

See what changed in the published release for persistent outcomes, change review, and reviewed HTTP and SQL profiles.

Try experimental ownership

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

[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

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

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.

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 · CI workflow

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. Compare installation, source, and runtime versions · Platform matrix · Standalone CLI and Rust library

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 · Build the docs · MIT license

Metadata

Release files for codepact 0.10.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for codepact 0.10.0
File Size Uploaded Provenance Actions
codepact-0.10.0.tar.gz 7.5 kB Without provenance Details for codepact-0.10.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for codepact 0.10.0
File Interpreter ABI Platform Actions
codepact-0.10.0-py3-none-any.whl Python 3 none any Details for codepact-0.10.0-py3-none-any.whl

Total release size: 16.3 kB

Release files / codepact-0.10.0.tar.gz

Download URL codepact-0.10.0.tar.gz
Size 7.5 kB
Tags Source
SHA-256 checksum
How to use checksums
078540ca47e79325ca269ca39ca508f127cca8b92067302ce735b6121fbe398f
BLAKE2b-256 checksum
How to use checksums
e8f600be63aafc430c6c460955fe6e188442c3b854f47388d19e79ceb22667ea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Release files / codepact-0.10.0-py3-none-any.whl

Download URL codepact-0.10.0-py3-none-any.whl
Size 8.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fa432bfd1f641731cb3db87f6d4ab03cc95542fab36b207ef5b29d5cf9ca83ec
BLAKE2b-256 checksum
How to use checksums
1ee1a5f5bea936bc16c50dae6987018896740619a12d0420832df299ccd1c4d1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.13.16

Security for codepact 0.10.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page