Pact Python - Quick Reference for AI Agents

Commands

Test:
```
hatch run test
```
(all tests) or call
```
pytest
```
directly.
Lint:
```
hatch run lint --fix
```
(check+fix) or
```
hatch run format
```
(auto-fix)
Typecheck:
```
hatch run typecheck
```
(all)
Examples:
```
hatch run example
```
(run example tests)
All checks:
```
hatch run all
```
(format, lint, test, typecheck)
V2 tests:
```
hatch run v2-test:test
```
(legacy v2 compatibility tests)

Imports: Use generic types (
```
Iterable
```
,
```
Sequence
```
,
```
Mapping
```
) over concrete (
```
list
```
,
```
dict
```
). Absolute imports only (no relative).
Types: All functions require type annotations. Use
```
typing
```
module for generics.
Docstrings: Google-style with Markdown formatting. Link references:
```
[ClassName.method][pact.module.ClassName.method]
```
Formatting: Use
```
ruff
```
for linting/formatting.
Naming: Follow PEP 8. Use descriptive names that indicate purpose.
Error handling: Use built-in exceptions (
```
ValueError
```
,
```
TypeError
```
) for standard errors. Custom exceptions inherit from
```
PactError
```
.
Validation: Use early returns to reduce nesting.
Comments: Explain design decisions, not what code does. No comments unless necessary.

Framework:
```
pytest
```
with files prefixed
```
test_
```
. Use
```
@pytest.mark.parametrize
```
for multiple scenarios.
Coverage: Focus on critical paths, edge cases, error conditions.
Fixtures: Use pytest fixtures for shared setup. Minimize mocking.

```
src/pact/
```
: Main V3+ codebase (active development)
```
src/pact/v2/
```
: Legacy V2 code (maintenance only - no new features)
```
pact-python-ffi/
```
: Low-level FFI bindings (memory management, type conversion only)
```
pact-python-cli/
```
: CLI wrapper (bundled binaries with system fallback)

Test:
```
hatch run test
```
(all tests) or call
```
pytest
```
directly.
Lint:
```
hatch run lint --fix
```
(check+fix) or
```
hatch run format
```
(auto-fix)
Typecheck:
```
hatch run typecheck
```
(all)
Examples:
```
hatch run example
```
(run example tests)
All checks:
```
hatch run all
```
(format, lint, test, typecheck)
V2 tests:
```
hatch run v2-test:test
```
(legacy v2 compatibility tests)

Imports: Use generic types (
```
Iterable
```
,
```
Sequence
```
,
```
Mapping
```
) over concrete (
```
list
```
,
```
dict
```
). Absolute imports only (no relative).
Types: All functions require type annotations. Use
```
typing
```
module for generics.
Docstrings: Google-style with Markdown formatting. Link references:
```
[ClassName.method][pact.module.ClassName.method]
```
Formatting: Use
```
ruff
```
for linting/formatting.
Naming: Follow PEP 8. Use descriptive names that indicate purpose.
Error handling: Use built-in exceptions (
```
ValueError
```
,
```
TypeError
```
) for standard errors. Custom exceptions inherit from
```
PactError
```
.
Validation: Use early returns to reduce nesting.
Comments: Explain design decisions, not what code does. No comments unless necessary.

Framework:
```
pytest
```
with files prefixed
```
test_
```
. Use
```
@pytest.mark.parametrize
```
for multiple scenarios.
Coverage: Focus on critical paths, edge cases, error conditions.
Fixtures: Use pytest fixtures for shared setup. Minimize mocking.

```
src/pact/
```
: Main V3+ codebase (active development)
```
src/pact/v2/
```
: Legacy V2 code (maintenance only - no new features)
```
pact-python-ffi/
```
: Low-level FFI bindings (memory management, type conversion only)
```
pact-python-cli/
```
: CLI wrapper (bundled binaries with system fallback)