python-ddd-framework 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

python_ddd_framework/caching/catalog.py

@@ -1,73 +0,0 @@
-"""Cache metadata 的 Application-local 动态聚合与 immutable view。"""
-
-from __future__ import annotations
-
-from collections.abc import Iterator, Mapping
-from types import MappingProxyType
-from typing import Any
-
-from ..modularity import ModuleRegistry
-from .contracts import CacheDefinition
-from .errors import CacheDefinitionError
-
-
-class CacheCatalog:
-    __slots__ = ("_definitions",)
-
-    def __init__(self, definitions: tuple[CacheDefinition[Any], ...]) -> None:
-        by_name: dict[str, CacheDefinition[Any]] = {}
-        for definition in definitions:
-            if not isinstance(definition, CacheDefinition):
-                raise CacheDefinitionError(
-                    cache=repr(definition),
-                    reason="catalog entries must be CacheDefinition values",
-                )
-            if definition.name in by_name:
-                raise CacheDefinitionError(
-                    cache=definition.name,
-                    reason="cache is declared more than once",
-                )
-            by_name[definition.name] = definition
-        self._definitions: Mapping[str, CacheDefinition[Any]] = MappingProxyType(
-            dict(sorted(by_name.items()))
-        )
-
-    @property
-    def definitions(self) -> tuple[CacheDefinition[Any], ...]:
-        return tuple(self._definitions.values())
-
-    def __iter__(self) -> Iterator[str]:
-        return iter(self._definitions)
-
-    def get(self, name: str) -> CacheDefinition[Any] | None:
-        return self._definitions.get(name)
-
-    def owns(self, definition: CacheDefinition[Any]) -> bool:
-        return self._definitions.get(definition.name) is definition
-
-
-def _build_cache_catalog(registry: ModuleRegistry) -> CacheCatalog:
-    definitions: list[CacheDefinition[Any]] = []
-    owners: dict[str, str] = {}
-    for descriptor in registry.dependency_order:
-        declared = descriptor.module_type.cache_definitions
-        if not isinstance(declared, tuple):
-            raise CacheDefinitionError(
-                cache=str(descriptor.key),
-                reason="Module cache_definitions must be an immutable tuple",
-            )
-        for definition in declared:
-            if not isinstance(definition, CacheDefinition):
-                raise CacheDefinitionError(
-                    cache=str(descriptor.key),
-                    reason="Module cache_definitions contains an invalid item",
-                )
-            previous = owners.get(definition.name)
-            if previous is not None:
-                raise CacheDefinitionError(
-                    cache=definition.name,
-                    reason=f"cache is already owned by {previous}",
-                )
-            owners[definition.name] = str(descriptor.key)
-            definitions.append(definition)
-    return CacheCatalog(tuple(definitions))

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/cache.py.jinja

@@ -1,10 +0,0 @@
-"""缓存契约只声明一次；提交后处理负责失效。"""
-
-from datetime import timedelta
-
-from python_ddd_framework.caching import CacheDefinition
-
-from ..application_contracts.orders import OrderView
-from ..domain_shared.definitions import MODULE_NAME
-
-ORDER_CACHE = CacheDefinition(f"{MODULE_NAME}.view", OrderView, ttl=timedelta(minutes=1))

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/events.py.jinja

@@ -1,24 +0,0 @@
-"""提交后失效缓存与通知；失败不伪装成数据库未提交，不承诺跨进程事件投递。"""
-
-from python_ddd_framework import LocalEventPhase, local_event_handler
-from python_ddd_framework.caching import DistributedCache
-from python_ddd_framework.realtime import RealtimePublisher
-
-from ..domain.orders import OrderChanged
-from ..domain_shared.definitions import ORDER_CHANGED_MESSAGE
-from .cache import ORDER_CACHE
-
-
-@local_event_handler(phase=LocalEventPhase.AFTER_COMMIT)
-class OrderChangedHandler:
-    def __init__(self, cache: DistributedCache, realtime: RealtimePublisher) -> None:
-        self._cache, self._realtime = cache, realtime
-
-    async def handle(self, event: OrderChanged) -> None:
-        await self._cache.remove(ORDER_CACHE, str(event.order_id))
-        if event.user_id is not None:
-            await self._realtime.send_to_user(
-                event.user_id,
-                message_type=ORDER_CHANGED_MESSAGE,
-                payload={"id": str(event.order_id), "status": event.status.value},
-            )

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/orders.py.jinja

@@ -1,83 +0,0 @@
-"""正式应用服务共用验证、授权、审计和 UoW；业务层不接触框架执行器。"""
-
-import logging
-from uuid import UUID, uuid4
-
-from python_ddd_framework import ApplicationService, CurrentUser
-from python_ddd_framework.authorization import authorize
-from python_ddd_framework.background_jobs import BackgroundJobEnqueuer
-from python_ddd_framework.caching import DistributedCache
-from python_ddd_framework.errors import BusinessError
-from python_ddd_framework.errors.base import ResourceConflictError, ResourceNotFoundError
-from python_ddd_framework.fastapi import http
-
-from ..application_contracts.orders import (
-{%- for contract in ["ApproveOrder", "CreateOrder", "OrderView", cookiecutter.class_prefix ~ "ApplicationService"] | sort %}
-    {{ contract }},
-{%- endfor %}
-)
-from ..domain.orders import Order, OrderTitle
-from ..domain.repository import OrderRepository
-from ..domain.settings import APPROVAL_ENABLED
-from ..domain_shared.definitions import APPROVAL_DISABLED, ORDERS_READ, ORDERS_WRITE
-from .cache import ORDER_CACHE
-from .tasks import ApprovalJob, ApprovalPayload
-
-logger = logging.getLogger(__name__)
-
-
-class _{{ cookiecutter.class_prefix }}ApplicationService(ApplicationService, {{ cookiecutter.class_prefix }}ApplicationService):
-    def __init__(
-        self,
-        repository: OrderRepository,
-        cache: DistributedCache,
-        jobs: BackgroundJobEnqueuer,
-        user: CurrentUser,
-    ) -> None:
-        self._repository, self._cache, self._jobs, self._user = repository, cache, jobs, user
-
-    @authorize(ORDERS_WRITE)
-    @http.post(status_code=201)
-    async def create(self, command: CreateOrder) -> OrderView:
-        order = Order.create(uuid4(), OrderTitle(value=command.title))
-        await self._repository.save(order)
-        logger.info("Order created")
-        return OrderView.model_validate(order)
-
-    @authorize(ORDERS_READ)
-    async def get(self, id: UUID) -> OrderView:
-        cached = await self._cache.get(ORDER_CACHE, str(id))
-        if cached is not None:
-            return cached
-        order = await self._repository.get(id)
-        if order is None:
-            raise ResourceNotFoundError("Order not found")
-        view = OrderView.model_validate(order)
-        await self._cache.set(ORDER_CACHE, str(id), view)
-        return view
-
-    @authorize(ORDERS_READ)
-    async def get_list(self) -> tuple[OrderView, ...]:
-        return tuple(OrderView.model_validate(order) for order in await self._repository.get_list())
-
-    @authorize(ORDERS_WRITE)
-    async def approve(self, id: UUID, command: ApproveOrder) -> OrderView:
-        if not await self.setting_provider.get(APPROVAL_ENABLED):
-            raise BusinessError(APPROVAL_DISABLED)
-        order = await self._repository.get(id)
-        if order is None:
-            raise ResourceNotFoundError("Order not found")
-        if order.version != command.expected_version:
-            raise ResourceConflictError("Order version changed")
-        order.approve(user_id=self._user.user_id)
-        await self._repository.save(order)
-        logger.info("Order approved")
-        return OrderView.model_validate(order)
-
-    @authorize(ORDERS_WRITE)
-    @http.post(status_code=202)
-    async def queue_approval(self, id: UUID) -> str:
-        if await self._repository.get(id) is None:
-            raise ResourceNotFoundError("Order not found")
-        # 入队参与本方法原生事务；失败时订单业务与队列写入一起回滚。
-        return await self._jobs.enqueue(ApprovalJob, ApprovalPayload(order_id=id))

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/tasks.py.jinja

@@ -1,84 +0,0 @@
-"""非持久 Worker 与持久 Job 分开；Job 重复投递由业务状态保证幂等。"""
-
-import logging
-from datetime import timedelta
-from uuid import UUID
-
-from pydantic import BaseModel, ConfigDict
-from python_ddd_framework import (
-    BackgroundWorker,
-    BackgroundWorkerContext,
-    Options,
-)
-from python_ddd_framework.background_jobs import (
-    BackgroundJobContext,
-    BackgroundJobHandler,
-)
-from python_ddd_framework.distributed_lock import DistributedLock
-from python_ddd_framework.settings import SettingProvider
-
-from ..domain.repository import OrderRepository
-from ..domain.settings import APPROVAL_ENABLED
-from ..domain_shared.definitions import MODULE_NAME, OrderStatus
-from .options import {{ cookiecutter.class_prefix }}Options
-
-logger = logging.getLogger(__name__)
-
-
-class ApprovalPayload(BaseModel):
-    model_config = ConfigDict(frozen=True, extra="forbid")
-    order_id: UUID
-
-
-class ApprovalJob(BackgroundJobHandler[ApprovalPayload]):
-    name = f"{MODULE_NAME}.approve"
-    version = 1
-    current = True
-    timeout = timedelta(seconds=30)
-
-    def __init__(
-        self,
-        repository: OrderRepository,
-        settings: SettingProvider,
-        options: Options[{{ cookiecutter.class_prefix }}Options],
-    ) -> None:
-        self._repository, self._settings, self._options = repository, settings, options
-
-    async def execute(self, payload: ApprovalPayload, context: BackgroundJobContext) -> None:
-        if self._options.value.allow_background_approval and await self._settings.get(
-            APPROVAL_ENABLED
-        ):
-            order = await self._repository.get(payload.order_id)
-            if order is not None and order.status is OrderStatus.PENDING:
-                order.approve()
-                await self._repository.save(order)
-
-
-class OrderMaintenanceWorker(BackgroundWorker):
-    name = f"{MODULE_NAME}.maintenance"
-    enabled = False
-    interval = timedelta(seconds=30)
-    iteration_timeout = timedelta(seconds=10)
-
-    def __init__(self, repository: OrderRepository, lock: DistributedLock) -> None:
-        self._repository, self._lock = repository, lock
-
-    async def run_iteration(self, context: BackgroundWorkerContext) -> None:
-        # 租约失效由框架请求取消并等待本轮清理；业务不吞 CancelledError。
-        async with self._lock.acquire(f"{MODULE_NAME}:maintenance") as acquired:
-            if acquired:
-                orders = await self._repository.get_list()
-                logger.info("Order maintenance completed: %s", len(orders))
-
-
-class OrderStatisticsWorker(BackgroundWorker):
-    name = f"{MODULE_NAME}.statistics"
-    enabled = False
-    interval = timedelta(minutes=5)
-    iteration_timeout = timedelta(seconds=10)
-
-    def __init__(self, repository: OrderRepository) -> None:
-        self._repository = repository
-
-    async def run_iteration(self, context: BackgroundWorkerContext) -> None:
-        logger.info("Order count: %s", len(await self._repository.get_list()))

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/orders.py.jinja

@@ -1,35 +0,0 @@
-"""DTO 只依赖共享定义；HTTP 与进程内调用共用同一验证管线。"""
-
-from typing import Protocol
-from uuid import UUID
-
-from pydantic import BaseModel, ConfigDict, Field
-from python_ddd_framework import ApplicationServiceContract
-
-from ..domain_shared.definitions import TITLE_MAX_LENGTH, OrderStatus
-
-
-class CreateOrder(BaseModel):
-    model_config = ConfigDict(frozen=True, extra="forbid")
-    title: str = Field(min_length=1, max_length=TITLE_MAX_LENGTH)
-
-
-class ApproveOrder(BaseModel):
-    model_config = ConfigDict(frozen=True, extra="forbid")
-    expected_version: int = Field(ge=1)
-
-
-class OrderView(BaseModel):
-    model_config = ConfigDict(frozen=True, from_attributes=True)
-    id: UUID
-    title: str
-    status: OrderStatus
-    version: int
-
-
-class {{ cookiecutter.class_prefix }}ApplicationService(ApplicationServiceContract, Protocol):
-    async def create(self, command: CreateOrder) -> OrderView: ...
-    async def get(self, id: UUID) -> OrderView: ...
-    async def get_list(self) -> tuple[OrderView, ...]: ...
-    async def approve(self, id: UUID, command: ApproveOrder) -> OrderView: ...
-    async def queue_approval(self, id: UUID) -> str: ...

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/repository.py.jinja

@@ -1,14 +0,0 @@
-"""领域需要的业务仓储边界；不暴露 Session 或容器。"""
-
-from typing import Protocol
-from uuid import UUID
-
-from python_ddd_framework import RepositoryContract
-
-from .orders import Order
-
-
-class OrderRepository(RepositoryContract, Protocol):
-    async def get(self, id: UUID) -> Order | None: ...
-    async def get_list(self) -> tuple[Order, ...]: ...
-    async def save(self, order: Order) -> None: ...

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain/seeding.py.jinja

@@ -1,19 +0,0 @@
-"""仅 pddd db seed 显式调用；确定性业务 ID 保证重复初始化不产生新订单。"""
-
-from uuid import NAMESPACE_URL, uuid5
-
-from python_ddd_framework import DataSeedContributor
-
-from ..domain_shared.definitions import MODULE_NAME
-from .orders import Order, OrderTitle
-from .repository import OrderRepository
-
-
-class {{ cookiecutter.class_prefix }}SeedContributor(DataSeedContributor):
-    def __init__(self, repository: OrderRepository) -> None:
-        self._repository = repository
-
-    async def seed(self) -> None:
-        id = uuid5(NAMESPACE_URL, f"{MODULE_NAME}:sample-order")
-        if await self._repository.get(id) is None:
-            await self._repository.save(Order.create(id, OrderTitle(value="Sample order")))

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/domain_shared/definitions.py.jinja

@@ -1,24 +0,0 @@
-"""修改业务名称、权限和约束的单一位置。"""
-
-from enum import Enum
-
-from python_ddd_framework import PermissionName
-from python_ddd_framework.errors import BusinessErrorDefinition
-
-MODULE_NAME = "{{ cookiecutter.module_name }}"
-ORDER_CHANGED_MESSAGE = f"{MODULE_NAME}.changed.v1"
-ORDER_SNAPSHOT_MESSAGE = f"{MODULE_NAME}.snapshot.v1"
-TITLE_MAX_LENGTH = 120
-ORDERS_READ = PermissionName(f"{MODULE_NAME}.read")
-ORDERS_WRITE = PermissionName(f"{MODULE_NAME}.write")
-ALREADY_APPROVED = BusinessErrorDefinition(
-    f"{MODULE_NAME}.already_approved", "Order is already approved"
-)
-APPROVAL_DISABLED = BusinessErrorDefinition(
-    f"{MODULE_NAME}.approval_disabled", "Order approval is disabled"
-)
-
-
-class OrderStatus(str, Enum):
-    PENDING = "pending"
-    APPROVED = "approved"

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/http_api/realtime.py.jinja

@@ -1,36 +0,0 @@
-"""单进程在线通知；连接认证由框架管理，业务授权仍经过服务契约。"""
-
-from typing import Annotated
-
-from fastapi import APIRouter, Depends
-from pydantic import BaseModel, ConfigDict
-from python_ddd_framework import FrameworkError
-from python_ddd_framework.fastapi import WebSocketConnection, websocket_connection
-from starlette.websockets import WebSocketDisconnect
-
-from ..application_contracts.orders import {{ cookiecutter.class_prefix }}ApplicationService
-from ..domain_shared.definitions import MODULE_NAME, ORDER_SNAPSHOT_MESSAGE
-
-router = APIRouter()
-
-
-class RefreshOrders(BaseModel):
-    model_config = ConfigDict(frozen=True, extra="forbid")
-
-
-@router.websocket(f"/ws/{MODULE_NAME}")
-async def orders_socket(
-    connection: Annotated[WebSocketConnection, Depends(websocket_connection)],
-) -> None:
-    try:
-        while True:
-            orders = await connection.invoke({{ cookiecutter.class_prefix }}ApplicationService.get_list)
-            await connection.send(
-                ORDER_SNAPSHOT_MESSAGE,
-                {"orders": [item.model_dump(mode="json") for item in orders]},
-            )
-            await connection.receive(RefreshOrders)
-    except WebSocketDisconnect:
-        return
-    except FrameworkError as error:
-        await connection.send_problem(error)

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/repositories/orders.py.jinja

@@ -1,49 +0,0 @@
-"""仓储参与当前 UoW，成功暂存后由 operation 收集聚合事件。"""
-
-from uuid import UUID
-
-from python_ddd_framework import OptimisticConcurrencyError
-from python_ddd_framework.sqlalchemy import SqlAlchemySessionProvider
-from sqlalchemy import select
-
-from ...domain.orders import Order, OrderTitle
-from ...domain.repository import OrderRepository
-from ...domain_shared.definitions import OrderStatus
-from ..models.orders import OrderRow
-
-
-class SqlAlchemyOrderRepository(OrderRepository):
-    def __init__(self, provider: SqlAlchemySessionProvider) -> None:
-        self._provider = provider
-
-    async def get(self, id: UUID) -> Order | None:
-        async with self._provider.operation("get"):
-            row = await (await self._provider.get_session()).get(OrderRow, id)
-            return None if row is None else _order(row)
-
-    async def get_list(self) -> tuple[Order, ...]:
-        async with self._provider.operation("get_list"):
-            rows = await (await self._provider.get_session()).scalars(
-                select(OrderRow).order_by(OrderRow.created_at, OrderRow.id)
-            )
-            return tuple(_order(row) for row in rows)
-
-    async def save(self, order: Order) -> None:
-        async with self._provider.operation("save", aggregate=order):
-            session = await self._provider.get_session()
-            row = await session.get(OrderRow, order.id)
-            if row is None:
-                if order.version:
-                    raise OptimisticConcurrencyError
-                row = OrderRow(id=order.id)
-                session.add(row)
-            elif row.version != order.version:
-                raise OptimisticConcurrencyError
-            order.stage_next_version(order.version)
-            row.title, row.status, row.version = order.title, order.status.value, order.version
-
-
-def _order(row: OrderRow) -> Order:
-    return Order(
-        row.id, OrderTitle(value=row.title), status=OrderStatus(row.status), version=row.version
-    )