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.10 through 3.14.
Install
pip install pyuow # core
pip install "pyuow[sqlalchemy]" # with SQLAlchemy integration
Python ≥ 3.10.
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
2 maintainers
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file pyuow-0.11.1.tar.gz.
File metadata
- Download URL: pyuow-0.11.1.tar.gz
- Upload date:
- Size: 25.5 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
poetry/2.4.1 CPython/3.14.7 Linux/6.17.0-1022-azure
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
df20c3342db32c21e988cbd23765eedbe2ddf5265586ab7dae48e99c9784c06b
|
|
| MD5 |
0daba7f41dba4bd06ccd35707455020a
|
|
| BLAKE2b-256 |
49fe3130aba8df43860d5359b5e0eea1055a9742f4e24e6a600e0d9c22a2316b
|
File details
Details for the file pyuow-0.11.1-py3-none-any.whl.
File metadata
- Download URL: pyuow-0.11.1-py3-none-any.whl
- Upload date:
- Size: 58.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
poetry/2.4.1 CPython/3.14.7 Linux/6.17.0-1022-azure
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
899ff7b744916285ada136ef0c4de5c8a87ce9fb933637c23e3b8f0b4c2bcda6
|
|
| MD5 |
022d1976591b790684c886c76dfecabd
|
|
| BLAKE2b-256 |
d78f059565c3ad4d900f73dac9f887885768bac66987cce771c0bd3ed64d48da
|
