Unit of Work for Python — composable units, transactional work managers, and a domain model toolkit.
📖 Read the docs · Quickstart · PyPI
What is PyUoW?
PyUoW is a Python implementation of the Unit of Work behavioural pattern. It gives you small, typed building blocks for business logic that compose into a flow and run inside a Work Manager that handles transactions, batching, and domain events.
The result: business logic that reads top-to-bottom, separates orchestration from execution, and stays testable as it grows.
Highlights
- Composable units — write each step as a
ConditionalUnit/RunUnit/FinalUnit, chain them with>>, validate the chain at build time. - Transactional out of the box — a SQLAlchemy adapter ships in
pyuow.contrib.sqlalchemy(sync + async), with nested-transaction support. - Domain-first —
Entity,AuditedEntity,SoftDeletableEntity,VersionedEntity, and an event-emittingModelbase, all immutable dataclasses. - Sync and async parity — every primitive has an
aio/twin; pick one per flow. - Strict types — passes
mypy --strict; runs on Python 3.11 through 3.15.
Install
pip install pyuow # core
pip install "pyuow[sqlalchemy]" # with SQLAlchemy integration
Python ≥ 3.11.
AI-agent skill
After installing, run pyuow install-skill to drop an AI-agent skill file into your project so Claude Code / OpenCode learn PyUoW's idioms. Add --global to install for your user account, or --check to dry-run.
See the step-by-step guide (or docs/install-skill.md).
At a glance
from dataclasses import dataclass
from pyuow import (
BaseContext, BaseParams, ConditionalUnit, ErrorUnit,
FinalUnit, Result, RunUnit,
)
from pyuow.work.noop import NoOpWorkManager
@dataclass(frozen=True)
class Greeting(BaseParams):
name: str
@dataclass
class Ctx(BaseContext[Greeting]):
params: Greeting
class IsNamePresent(ConditionalUnit[Ctx, str]):
def condition(self, ctx: Ctx) -> bool:
return bool(ctx.params.name)
class Greet(RunUnit[Ctx, str]):
def run(self, ctx: Ctx) -> None:
print(f"Hello, {ctx.params.name}!")
class Done(FinalUnit[Ctx, str]):
def finish(self, ctx: Ctx) -> Result[str]:
return Result.ok("greeted")
flow = (
IsNamePresent(on_failure=ErrorUnit(exc=ValueError("name required")))
>> Greet()
>> Done()
).build()
result = NoOpWorkManager().by(flow).do_with(Ctx(params=Greeting(name="Alice")))
assert result.get() == "greeted"
What's in the box
| Concept | What it gives you |
|---|---|
| Units & Flow | ConditionalUnit / RunUnit / FinalUnit / ErrorUnit, chained with >> |
| Result | ok / error / empty plus .map, .and_then, .unwrap_or |
| Context | Mutable, immutable, and domain-aware context bases |
| Work Manager | NoOp, transactional, and domain-transactional managers |
| Domain Model | Entity, AuditedEntity, Model, Batch, events, typed exceptions |
| DataPoints | Typed producer / consumer contracts between units |
| SQLAlchemy | Ready-made entity and view repositories, table mixins, transaction manager |
| Async | A sync and an aio/ twin for every primitive |
Contributing
PRs welcome — see CONTRIBUTING.md for the dev setup, or run:
poetry install --with docs
make tests # pytest + coverage
make fmt # ruff + mypy
make docs-serve # live preview at http://127.0.0.1:8000
Metadata
Release files for pyuow 0.12.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| pyuow-0.12.0.tar.gz | 25.5 kB | Without provenance | Details for pyuow-0.12.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyuow-0.12.0-py3-none-any.whl | Python 3 | none | any | Details for pyuow-0.12.0-py3-none-any.whl |
Total release size: 83.8 kB
Release files / pyuow-0.12.0.tar.gz
| Download URL | pyuow-0.12.0.tar.gz |
|---|---|
| Size | 25.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
2846fa3ff211edb0ee82e90d90f41265c2b43d23ef39316c6ff4bb67f2023f5a
|
|
BLAKE2b-256 checksum How to use checksums |
32b1b303cc447fa129beb3b2c8ab08674a375454729f6b650ebc4df79a27125b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.5.1 CPython/3.14.10 Linux/7.0.0-1017-azure
|
Release files / pyuow-0.12.0-py3-none-any.whl
| Download URL | pyuow-0.12.0-py3-none-any.whl |
|---|---|
| Size | 58.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
fb2b1776d7a2518e6efc966bf0c0572981360066ff7477933a932162d2cc2317
|
|
BLAKE2b-256 checksum How to use checksums |
8aa13f2630be2ce8bf6792078367877106a76af47ce05f39bea8783e54623350
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
poetry/2.5.1 CPython/3.14.10 Linux/7.0.0-1017-azure
|
Security for pyuow 0.12.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.