Skip to main content

pyUoW

Unit of Work for Python — composable units, transactional work managers, and a domain model toolkit.

📖 Read the docs  ·  Quickstart  ·  PyPI

Downloads Build Codecov Ruff Python versions License


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-emitting Model base, 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)

Source distribution for pyuow 0.12.0
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)

Table of built distributions (wheels) for pyuow 0.12.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

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