oclarcdo

Reusable domain-layer building blocks for Python: aggregates, domain events, specifications, guard policies, persistence-oriented repository protocols, and transaction abstractions. No web framework or ORM dependency—use from FastAPI, Django, CLI tools, or any host.

This package is the Python equivalent of Odex.AspNetCore.Clarc.Domain on .NET.

Installation

pip install oclarcdo

With uv:

uv add oclarcdo

Pin a version for reproducible builds:

pip install oclarcdo==0.2.0

Requirements

How it fits in CLARC / clean architecture

Repository protocols accept callables for predicates so implementations can filter in memory or translate to SQL (for example with SQLAlchemy). Wiring DI, ORMs, outboxes, and mediators stays in Application and Infrastructure.

Capabilities

Examples

Aggregate and policy

from uuid import UUID, uuid4

from oclarcdo import AggregateEvent, BasePolicy, StatefulAggregate


class ProductRenamed(AggregateEvent):
    product_id: UUID
    new_name: str


class Product(StatefulAggregate[UUID]):
    def __init__(self, name: str) -> None:
        super().__init__()
        self.id = uuid4()
        self.name = name

    def rename(self, new_name: str) -> None:
        BasePolicy[str]().require_not_null_nor_empty(new_name)
        self.name = new_name
        self.mark_modified()
        self._add_event(ProductRenamed(product_id=self.id, new_name=new_name))

Specification

from oclarcdo import Specification


class ActiveUsersSpec(Specification[User]):
    def to_predicate(self):
        return lambda u: u.is_active


spec = ActiveUsersSpec().and_(UserNameContainsSpec("alex"))
await repository.list_async(spec.to_predicate())

Application service

from oclarcdo import AggregateService


class ProductService(AggregateService):
    def __init__(self, products: AggregateRepositoryProtocol[Product, UUID]) -> None:
        super().__init__(products)
        self._products = products

    async def create_async(self, name: str) -> Product:
        product = Product(name)
        await self._products.add_async(product)
        await self.save_repository_changes_async()
        return product

Development

See CONTRIBUTING.md.

git clone https://github.com/o-shabi/odex-clarc-domain-python.git
cd odex-clarc-domain-python
uv sync --all-groups
uv run pytest
uv run ruff check .
uv run mypy

License

MIT — Copyright (c) Asen O'Shabi. See LICENSE.

Links