python-ddd-framework 0.3.1__py3-none-any.whl

python_ddd_framework/diagnostics/journal.py

@@ -0,0 +1,174 @@
+"""单个 Application 拥有的 append-only diagnostic journal。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+from time import perf_counter_ns
+from uuid import UUID, uuid4
+
+from ..errors import InvalidDiagnosticCodeError
+from .model import (
+    DiagnosticMessage,
+    DiagnosticSnapshot,
+    EventStatus,
+    FailureRecord,
+    LifecyclePhase,
+    LifecycleStage,
+    PhaseEvent,
+    SourceLocation,
+)
+
+_DIAGNOSTIC_CODE_PUNCTUATION = frozenset("._-")
+_MAX_DIAGNOSTIC_CODE_LENGTH = 128
+
+
+@dataclass(frozen=True, slots=True)
+class _ActiveEvent:
+    phase: LifecyclePhase
+    stage: LifecycleStage
+    subject: str
+    source: SourceLocation | None
+    started_ns: int
+
+
+class _DiagnosticJournal:
+    """Application-owned journal；外部只能取得不可变的时点快照。"""
+
+    __slots__ = ("_events", "_failure_order", "_failures", "_messages", "_sequence")
+
+    def __init__(self) -> None:
+        self._sequence = 0
+        self._events: list[PhaseEvent] = []
+        self._messages: list[DiagnosticMessage] = []
+        self._failure_order: list[UUID] = []
+        self._failures: dict[UUID, FailureRecord] = {}
+
+    def _next_sequence(self) -> int:
+        self._sequence += 1
+        return self._sequence
+
+    def start_event(
+        self,
+        *,
+        phase: LifecyclePhase,
+        stage: LifecycleStage,
+        subject: str,
+        source: SourceLocation | None,
+    ) -> _ActiveEvent:
+        started_ns = perf_counter_ns()
+        active_event = _ActiveEvent(phase, stage, subject, source, started_ns)
+        self._events.append(
+            PhaseEvent(
+                sequence=self._next_sequence(),
+                phase=phase,
+                stage=stage,
+                subject=subject,
+                status=EventStatus.STARTED,
+                started_monotonic_ns=started_ns,
+                duration_ns=None,
+                source=source,
+                failure_id=None,
+            )
+        )
+        return active_event
+
+    def finish_event(
+        self,
+        active_event: _ActiveEvent,
+        *,
+        status: EventStatus,
+        failure_id: UUID | None,
+    ) -> int:
+        # start 返回的 value object 是一次事件的唯一事实，finish 不重复传递上下文。
+        duration_ns = perf_counter_ns() - active_event.started_ns
+        self._events.append(
+            PhaseEvent(
+                sequence=self._next_sequence(),
+                phase=active_event.phase,
+                stage=active_event.stage,
+                subject=active_event.subject,
+                status=status,
+                started_monotonic_ns=active_event.started_ns,
+                duration_ns=duration_ns,
+                source=active_event.source,
+                failure_id=failure_id,
+            )
+        )
+        return duration_ns
+
+    def begin_failure(
+        self,
+        *,
+        error_type: str,
+        phase: LifecyclePhase,
+        stage: LifecycleStage,
+        subject: str | None,
+        message: str,
+        source: SourceLocation | None,
+        dependency_path: tuple[str, ...],
+    ) -> UUID:
+        failure_id = uuid4()
+        # 先发布不可变记录，rollback 后替换 cleanup 关联，snapshot 不出现悬空引用。
+        failure = FailureRecord(
+            id=failure_id,
+            error_type=error_type,
+            phase=phase,
+            stage=stage,
+            subject=subject,
+            message=message,
+            source=source,
+            dependency_path=dependency_path,
+            cleanup_failure_ids=(),
+        )
+        self._failure_order.append(failure_id)
+        self._failures[failure_id] = failure
+        return failure_id
+
+    def complete_failure(
+        self,
+        failure_id: UUID,
+        *,
+        cleanup_failure_ids: tuple[UUID, ...] = (),
+    ) -> None:
+        self._failures[failure_id] = replace(
+            self._failures[failure_id], cleanup_failure_ids=cleanup_failure_ids
+        )
+
+    def emit(
+        self,
+        *,
+        phase: LifecyclePhase,
+        stage: LifecycleStage,
+        subject: str,
+        code: str,
+        source: SourceLocation | None,
+    ) -> None:
+        if not _is_diagnostic_code(code):
+            raise InvalidDiagnosticCodeError(code, max_length=_MAX_DIAGNOSTIC_CODE_LENGTH)
+        self._messages.append(
+            DiagnosticMessage(
+                sequence=self._next_sequence(),
+                phase=phase,
+                stage=stage,
+                subject=subject,
+                code=code,
+                source=source,
+            )
+        )
+
+    def snapshot(self, application_id: UUID) -> DiagnosticSnapshot:
+        failures = tuple(self._failures[failure_id] for failure_id in self._failure_order)
+        return DiagnosticSnapshot(
+            application_id=application_id,
+            events=tuple(self._events),
+            failures=failures,
+            messages=tuple(self._messages),
+        )
+
+
+def _is_diagnostic_code(code: str) -> bool:
+    if not code or len(code) > _MAX_DIAGNOSTIC_CODE_LENGTH or not code[0].isalpha():
+        return False
+    return all(
+        character.isalnum() or character in _DIAGNOSTIC_CODE_PUNCTUATION for character in code
+    )

python_ddd_framework/diagnostics/model.py

@@ -0,0 +1,83 @@
+"""不可变 diagnostic contract；不拥有 journal mutation。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+from uuid import UUID
+
+
+class LifecyclePhase(str, Enum):
+    COMPOSITION = "composition"
+    RUNTIME = "runtime"
+    CLEANUP = "cleanup"
+
+
+class LifecycleStage(str, Enum):
+    PRE_CONFIGURE = "pre_configure"
+    CONFIGURE = "configure"
+    POST_CONFIGURE = "post_configure"
+    PRE_INITIALIZE = "pre_initialize"
+    INITIALIZE = "initialize"
+    POST_INITIALIZE = "post_initialize"
+    SHUTDOWN = "shutdown"
+
+
+class EventStatus(str, Enum):
+    STARTED = "started"
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+
+
+@dataclass(frozen=True, slots=True)
+class SourceLocation:
+    owner: str
+    file: str | None
+    line: int | None
+    symbol: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class PhaseEvent:
+    sequence: int
+    phase: LifecyclePhase
+    stage: LifecycleStage
+    subject: str
+    status: EventStatus
+    started_monotonic_ns: int
+    duration_ns: int | None
+    source: SourceLocation | None
+    failure_id: UUID | None
+
+
+@dataclass(frozen=True, slots=True)
+class FailureRecord:
+    id: UUID
+    error_type: str
+    phase: LifecyclePhase
+    stage: LifecycleStage
+    subject: str | None
+    message: str
+    source: SourceLocation | None
+    dependency_path: tuple[str, ...]
+    cleanup_failure_ids: tuple[UUID, ...]
+
+
+@dataclass(frozen=True, slots=True)
+class DiagnosticMessage:
+    sequence: int
+    phase: LifecyclePhase
+    stage: LifecycleStage
+    subject: str
+    code: str
+    source: SourceLocation | None
+
+
+@dataclass(frozen=True, slots=True)
+class DiagnosticSnapshot:
+    """一次读取产生的不可变诊断视图，不随后续 lifecycle 变化。"""
+
+    application_id: UUID
+    events: tuple[PhaseEvent, ...]
+    failures: tuple[FailureRecord, ...]
+    messages: tuple[DiagnosticMessage, ...]

python_ddd_framework/diagnostics/source.py

@@ -0,0 +1,25 @@
+"""贡献诊断的调用位置；depth 由公开贡献入口指定。"""
+
+from __future__ import annotations
+
+import inspect
+
+from .model import SourceLocation
+
+
+def caller_source(owner: str, *, depth: int) -> SourceLocation:
+    frame = inspect.currentframe()
+    try:
+        for _ in range(depth):
+            frame = None if frame is None else frame.f_back
+        if frame is None:
+            return SourceLocation(owner=owner, file=None, line=None, symbol=None)
+        return SourceLocation(
+            owner=owner,
+            file=frame.f_code.co_filename,
+            line=frame.f_lineno,
+            symbol=frame.f_code.co_name,
+        )
+    finally:
+        # 不让 frame 引用延长 Module/composition 对象的生命周期。
+        del frame

python_ddd_framework/distributed_lock/__init__.py

@@ -0,0 +1,6 @@
+"""Provider-neutral 业务互斥与租约失败契约。"""
+
+from .contracts import DistributedLock, DistributedLockError
+from .options import DistributedLockOptions
+
+__all__ = ("DistributedLock", "DistributedLockError", "DistributedLockOptions")

python_ddd_framework/distributed_lock/contracts.py

@@ -0,0 +1,20 @@
+"""锁的业务使用与错误边界；provider 不进入稳定契约。"""
+
+from contextlib import AbstractAsyncContextManager
+from typing import Protocol
+
+from ..errors.base import FrameworkError
+
+
+class DistributedLock(Protocol):
+    def acquire(self, key: str, /) -> AbstractAsyncContextManager[bool]:
+        """进入后返回是否取得锁；持有者必须配合取消并在退出上下文前完成清理。"""
+        ...
+
+
+class DistributedLockError(FrameworkError):
+    def __init__(self, *, key: str, operation: str, error_type: str) -> None:
+        self.key = key
+        self.operation = operation
+        self.error_type = error_type
+        super().__init__(f"Distributed lock {key!r} {operation} failed with {error_type}")

python_ddd_framework/distributed_lock/options.py

@@ -0,0 +1,19 @@
+"""获取等待和租约时序的唯一默认值来源。"""
+
+from datetime import timedelta
+
+from pydantic import Field, model_validator
+
+from ..options import BaseOptions
+
+
+class DistributedLockOptions(BaseOptions):
+    wait_timeout: timedelta = Field(default=timedelta(seconds=5), ge=timedelta(0))
+    lease_timeout: timedelta = Field(default=timedelta(seconds=30), ge=timedelta(milliseconds=1))
+    renewal_interval: timedelta = Field(default=timedelta(seconds=10), ge=timedelta(milliseconds=1))
+
+    @model_validator(mode="after")
+    def _validate_renewal(self) -> "DistributedLockOptions":
+        if self.renewal_interval >= self.lease_timeout:
+            raise ValueError("renewal_interval must be shorter than lease_timeout")
+        return self

python_ddd_framework/domain/__init__.py

@@ -0,0 +1,13 @@
+"""Provider-neutral DDD foundations owned by Python DDD Framework."""
+
+from .aggregates import AggregateRoot
+from .entities import Entity
+from .errors import OptimisticConcurrencyError
+from .value_objects import ValueObject
+
+__all__ = (
+    "AggregateRoot",
+    "Entity",
+    "OptimisticConcurrencyError",
+    "ValueObject",
+)

python_ddd_framework/domain/aggregates.py

@@ -0,0 +1,64 @@
+"""Aggregate identity, version and pending local-event ownership."""
+
+from __future__ import annotations
+
+from dataclasses import is_dataclass
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel
+
+from .entities import Entity
+from .errors import OptimisticConcurrencyError
+
+_TId = TypeVar("_TId")
+
+
+class AggregateRoot(Entity[_TId], Generic[_TId]):
+    """一个 invocation 内聚合版本和待提交事件的唯一 mutable owner。"""
+
+    __slots__ = ("_local_events", "_version", "_version_staged")
+
+    def __init__(self, entity_id: _TId, *, version: int = 0) -> None:
+        super().__init__(entity_id)
+        if not isinstance(version, int) or isinstance(version, bool) or version < 0:
+            raise ValueError("aggregate version must be a non-negative integer")
+        self._version = version
+        self._version_staged = False
+        self._local_events: list[object] = []
+
+    @property
+    def version(self) -> int:
+        return self._version
+
+    def raise_local_event(self, event: object) -> None:
+        if not _is_immutable_event(event):
+            raise TypeError("aggregate local events must be immutable dataclass or Pydantic values")
+        self._local_events.append(event)
+
+    def release_local_events(self) -> tuple[object, ...]:
+        events = tuple(self._local_events)
+        self._local_events.clear()
+        return events
+
+    def stage_next_version(self, expected_version: int) -> int:
+        """Repository SPI：一次聚合实例只允许暂存一个下一版本。"""
+
+        if (
+            not isinstance(expected_version, int)
+            or isinstance(expected_version, bool)
+            or expected_version < 0
+        ):
+            raise ValueError("expected_version must be a non-negative integer")
+        if self._version_staged or self._version != expected_version:
+            raise OptimisticConcurrencyError
+        self._version += 1
+        self._version_staged = True
+        return self._version
+
+
+def _is_immutable_event(event: object) -> bool:
+    event_type = type(event)
+    dataclass_parameters = getattr(event_type, "__dataclass_params__", None)
+    if is_dataclass(event) and bool(getattr(dataclass_parameters, "frozen", False)):
+        return True
+    return isinstance(event, BaseModel) and event.model_config.get("frozen") is True

python_ddd_framework/domain/entities.py

@@ -0,0 +1,33 @@
+"""Entity identity semantics independent from persistence providers."""
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+_TId = TypeVar("_TId")
+
+
+class Entity(Generic[_TId]):
+    """Identity owner whose identifier cannot change after construction."""
+
+    __slots__ = ("_id",)
+
+    def __init__(self, entity_id: _TId) -> None:
+        if entity_id is None:
+            raise ValueError("entity id cannot be None")
+        self._id = entity_id
+
+    @property
+    def id(self) -> _TId:
+        return self._id
+
+    def __eq__(self, other: object) -> bool:
+        if self is other:
+            return True
+        if type(self) is not type(other):
+            return False
+        return self.id == other.id
+
+    def __hash__(self) -> int:
+        # 类型是 identity 的一部分，避免不同聚合偶然共用相同标识时发生碰撞语义。
+        return hash((type(self), self.id))

python_ddd_framework/domain/errors.py

@@ -0,0 +1,12 @@
+"""DDD boundary failures safe for transport mapping."""
+
+from __future__ import annotations
+
+from ..errors import ResourceConflictError
+
+
+class OptimisticConcurrencyError(ResourceConflictError):
+    """调用方版本与持久化 authority 不一致；不携带真实行版本或 SQL。"""
+
+    def __init__(self) -> None:
+        super().__init__("Aggregate version conflict")

python_ddd_framework/domain/value_objects.py

@@ -0,0 +1,31 @@
+"""Pydantic-backed immutable domain values."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict
+
+
+class ValueObject(BaseModel):
+    """按具体类型与字段值比较的领域值；它不是 transport DTO。"""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    @classmethod
+    def __pydantic_init_subclass__(cls, **kwargs: Any) -> None:
+        super().__pydantic_init_subclass__(**kwargs)
+        if cls.model_config.get("frozen") is not True or cls.model_config.get("extra") != "forbid":
+            raise TypeError("ValueObject subclasses must remain frozen and forbid extra fields")
+
+    def __eq__(self, other: object) -> bool:
+        if type(self) is not type(other):
+            return False
+        return self._field_values() == other._field_values()
+
+    def __hash__(self) -> int:
+        # 字段中含 list/dict 等 mutable value 时由 Python 原生 hash fail closed。
+        return hash((type(self), self._field_values()))
+
+    def _field_values(self) -> tuple[object, ...]:
+        return tuple(getattr(self, name) for name in type(self).model_fields)

python_ddd_framework/errors/__init__.py

@@ -0,0 +1,75 @@
+"""按 capability 组织的 Python DDD Framework 结构化错误公开边界。"""
+
+from .base import FrameworkError, ResourceConflictError, ResourceNotFoundError
+from .business import BusinessError, BusinessErrorDefinition, BusinessErrorField
+from .configuration import (
+    ConfigurationSourceError,
+    DuplicateOptionDefinitionError,
+    InvalidOptionDefinitionError,
+    OptionsContributionClosedError,
+    OptionsValidationError,
+    UnknownOptionsError,
+)
+from .diagnostics import InvalidDiagnosticCodeError
+from .lifecycle import (
+    ApplicationRuntimeError,
+    ApplicationStartError,
+    CompositionResourceError,
+    InvalidApplicationStateError,
+    LifecycleInvocationError,
+    LifecycleReturnValueError,
+)
+from .modularity import (
+    DuplicateModuleIdentityError,
+    GraphInvariantError,
+    InvalidModuleReferenceError,
+    ModuleCycleError,
+    ModuleInstantiationError,
+    ModuleResolutionError,
+    UnknownModuleError,
+)
+from .services import (
+    CatalogNativeGraphMismatchError,
+    ContainerCleanupError,
+    ContainerValidationError,
+    ConventionScanError,
+    InvalidConventionDefinitionError,
+    RegistrationConflictError,
+    ServiceContributorClosedError,
+)
+
+__all__ = (
+    "ApplicationRuntimeError",
+    "ApplicationStartError",
+    "BusinessError",
+    "BusinessErrorDefinition",
+    "BusinessErrorField",
+    "CatalogNativeGraphMismatchError",
+    "CompositionResourceError",
+    "ConfigurationSourceError",
+    "ContainerCleanupError",
+    "ContainerValidationError",
+    "ConventionScanError",
+    "DuplicateModuleIdentityError",
+    "DuplicateOptionDefinitionError",
+    "FrameworkError",
+    "GraphInvariantError",
+    "InvalidApplicationStateError",
+    "InvalidConventionDefinitionError",
+    "InvalidDiagnosticCodeError",
+    "InvalidModuleReferenceError",
+    "InvalidOptionDefinitionError",
+    "LifecycleInvocationError",
+    "LifecycleReturnValueError",
+    "ModuleCycleError",
+    "ModuleInstantiationError",
+    "ModuleResolutionError",
+    "OptionsContributionClosedError",
+    "OptionsValidationError",
+    "RegistrationConflictError",
+    "ResourceConflictError",
+    "ResourceNotFoundError",
+    "ServiceContributorClosedError",
+    "UnknownModuleError",
+    "UnknownOptionsError",
+)

python_ddd_framework/errors/base.py

@@ -0,0 +1,13 @@
+"""所有 capability error 共享的最小命名根。"""
+
+
+class FrameworkError(Exception):
+    """所有 Python DDD Framework 结构化错误的命名基类。"""
+
+
+class ResourceConflictError(FrameworkError):
+    """可信业务边界可映射为 HTTP 409 的静态冲突。"""
+
+
+class ResourceNotFoundError(FrameworkError):
+    """可信业务边界可映射为 HTTP 404 的静态缺失。"""

python_ddd_framework/errors/business.py

@@ -0,0 +1,53 @@
+"""业务模块集中定义的公开安全错误，不把异常正文或动态输入当作响应。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pydantic import BaseModel
+
+from .base import FrameworkError
+
+
+@dataclass(frozen=True, slots=True)
+class BusinessErrorDefinition:
+    code: str
+    message: str
+
+    def __post_init__(self) -> None:
+        if (
+            not isinstance(self.code, str)
+            or not self.code
+            or any(not (part.isascii() and (part.isalnum() or part in "._")) for part in self.code)
+        ):
+            raise ValueError("business error code must be a stable non-empty identifier")
+        if not isinstance(self.message, str) or not self.message.strip():
+            raise ValueError("business error message must be a static safe message")
+
+
+@dataclass(frozen=True, slots=True)
+class BusinessErrorField:
+    model_type: type[BaseModel]
+    name: str
+
+    def __post_init__(self) -> None:
+        # 字段必须来自静态 DTO contract，不能把运行时字典键或用户输入混入定位信息。
+        if not isinstance(self.model_type, type) or not issubclass(self.model_type, BaseModel):
+            raise TypeError("business error field requires a Pydantic model type")
+        if self.name not in self.model_type.model_fields:
+            raise ValueError("business error field must name a declared model field")
+
+
+class BusinessError(FrameworkError):
+    def __init__(
+        self, definition: BusinessErrorDefinition, *, fields: tuple[BusinessErrorField, ...] = ()
+    ) -> None:
+        if not isinstance(definition, BusinessErrorDefinition):
+            raise TypeError("business error requires a static definition")
+        if not isinstance(fields, tuple) or any(
+            not isinstance(field, BusinessErrorField) for field in fields
+        ):
+            raise TypeError("business error fields must be an immutable tuple")
+        self.definition = definition
+        self.fields = fields
+        super().__init__(definition.code)