python-seedwork 0.2.0

DDD and Hexagonal Architecture building blocks for Python

python-seedwork

DDD and Hexagonal Architecture building blocks for Python.

Goals

• Unify design patterns. Provide a shared vocabulary — entities, aggregates, value objects, domain events, CQRS buses — so every bounded context starts from the same foundation.
• Keep domain logic pure. The domain layer has zero framework or infrastructure imports. Business rules live in the domain; everything else lives in infrastructure.
• Clear layer boundaries. Protocols define contracts; implementations satisfy them structurally. The dependency direction is enforced: domain ← application ← infrastructure.

Installation

pip install python-seedwork

Requires Python 3.12+. Ships a py.typed marker (PEP 561) — mypy and pyright pick up the inline types automatically.

How to Use

See Getting Started for a step-by-step walkthrough: define a value object, build an aggregate root, create a command handler, and wire a bus.

The Component Reference covers every class and protocol in detail. A complete working example lives in docs/examples/bank_account/.

What's Included

Layer	Package	Components
Domain	seedwork.domain	Entity, AggregateRoot, ValueObject, DomainEvent, DomainEventRecord, DomainError, Repository, UnitOfWork
Application	seedwork.application	Command, Query[TResult], CommandHandler, QueryHandler, CommandBus, QueryBus, Result, DomainEventPublisher, DomainEventHandler
Infrastructure	seedwork.infrastructure	RegistryCommandBus, RegistryQueryBus, TransactionalCommandBus, CommandBusBuilder, QueryBusBuilder, DomainEventPublishingRepository, InMemoryRepository

All components are also re-exported from the top-level seedwork package.

Built With

• Python 3.12+
• uv — dependency management and packaging
• Ruff — linting and formatting
• Pyright — strict static type checking
• pytest — testing with coverage gate
• python-semantic-release — automated versioning and changelog

Development

Requirements: Python 3.12+, uv

git clone https://github.com/aseguragonzalez/python-seedwork.git
cd python-seedwork
make install

Command	Description
make check	Lint, typecheck, and tests (what CI runs)
make lint	Run ruff linter
make format	Format and auto-fix with ruff
make typecheck	Run pyright
make test	Run tests with coverage (90% gate)
make test-no-cov	Run tests without coverage
make clean	Remove build artifacts and caches

Documentation

• Getting Started — step-by-step guide for building with this library
• Component Reference — every class, protocol, and method
• Best Practices — patterns and idioms for effective use
• Coding Standards — conventions aligned with DDD and Clean Architecture

Contributing

This project follows the Conventional Commits specification. The commit-msg pre-commit hook enforces the format; python-semantic-release derives versions and the changelog from commit prefixes automatically.

References

• Evans, E. — Domain-Driven Design: Tackling Complexity in the Heart of Software (2003)
• Vernon, V. — Implementing Domain-Driven Design (2013)
• Martin, R. C. — Clean Architecture: A Craftsman's Guide to Software Structure and Design (2017)