python-platform 0.1.1__py3-none-any.whl

python_platform/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_platform/errors/__init__.py

@@ -0,0 +1,75 @@
+"""按 capability 组织的 Python Platform 结构化错误公开边界。"""
+
+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_platform/errors/base.py

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

python_platform/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)

python_platform/errors/configuration.py

@@ -0,0 +1,119 @@
+"""Configuration 与 typed Options 的结构化失败。"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import FrameworkError
+
+if TYPE_CHECKING:
+    from pydantic import BaseModel, ValidationError
+
+    from ..diagnostics import SourceLocation
+    from ..modularity import ModuleKey
+    from ..options import OptionsValidationIssue
+
+
+class ConfigurationSourceError(FrameworkError):
+    """配置来源加载或规范化失败；消息不复制可能含敏感值的底层异常文本。"""
+
+    def __init__(
+        self,
+        *,
+        source_id: str,
+        location: SourceLocation,
+        original_error: BaseException,
+    ) -> None:
+        self.source_id = source_id
+        self.location = location
+        self.original_error = original_error
+        self.__cause__ = original_error
+        self.__suppress_context__ = True
+        super().__init__(f"Unable to load configuration source {source_id!r}")
+
+
+class InvalidOptionDefinitionError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        owner: ModuleKey,
+        model_type: type[BaseModel] | None,
+        option_kind: str,
+        reason: str,
+    ) -> None:
+        self.owner = owner
+        self.model_type = model_type
+        self.option_kind = option_kind
+        self.reason = reason
+        model_name = (
+            f"{model_type.__module__}.{model_type.__qualname__}"
+            if model_type is not None
+            else "<invalid declaration>"
+        )
+        super().__init__(
+            f"Invalid {option_kind} definition {model_name} declared by {owner}: {reason}"
+        )
+
+
+class DuplicateOptionDefinitionError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        model_type: type[BaseModel],
+        option_kind: str,
+        first_owner: ModuleKey,
+        second_owner: ModuleKey,
+    ) -> None:
+        self.model_type = model_type
+        self.option_kind = option_kind
+        self.first_owner = first_owner
+        self.second_owner = second_owner
+        model_name = f"{model_type.__module__}.{model_type.__qualname__}"
+        super().__init__(
+            f"Duplicate {option_kind} definition for {model_name}: {first_owner} and {second_owner}"
+        )
+
+
+class UnknownOptionsError(FrameworkError, KeyError):
+    def __init__(self, model_type: type[BaseModel], *, option_kind: str) -> None:
+        self.model_type = model_type
+        self.option_kind = option_kind
+        model_name = f"{model_type.__module__}.{model_type.__qualname__}"
+        super().__init__(f"Unknown {option_kind} model {model_name}")
+
+
+class OptionsContributionClosedError(FrameworkError):
+    def __init__(self, *, option_kind: str, stage: str) -> None:
+        self.option_kind = option_kind
+        self.stage = stage
+        super().__init__(
+            f"{option_kind} configuration contribution is no longer active after {stage}"
+        )
+
+
+class OptionsValidationError(FrameworkError):
+    """对 Pydantic 错误增加 owner/source 语义，只保留已脱敏的 Pydantic cause。"""
+
+    def __init__(
+        self,
+        *,
+        model_type: type[BaseModel],
+        section: str,
+        owner: ModuleKey,
+        option_kind: str,
+        issues: tuple[OptionsValidationIssue, ...],
+        validation_error: ValidationError,
+    ) -> None:
+        self.model_type = model_type
+        self.section = section
+        self.owner = owner
+        self.option_kind = option_kind
+        self.issues = issues
+        self.validation_error = validation_error
+        self.__cause__ = validation_error
+        self.__suppress_context__ = True
+        model_name = f"{model_type.__module__}.{model_type.__qualname__}"
+        paths = ", ".join(issue.field_path for issue in issues) or "<model>"
+        super().__init__(
+            f"Invalid {option_kind} {model_name} at section {section!r}; fields: {paths}"
+        )

python_platform/errors/diagnostics.py

@@ -0,0 +1,12 @@
+"""Diagnostic contract 自身的边界错误。"""
+
+from .base import FrameworkError
+
+
+class InvalidDiagnosticCodeError(FrameworkError):
+    def __init__(self, code: str, *, max_length: int) -> None:
+        self.code = code
+        self.max_length = max_length
+        super().__init__(
+            f"Diagnostic code must be a stable identifier of at most {max_length} characters"
+        )

python_platform/errors/lifecycle.py

@@ -0,0 +1,164 @@
+"""Application state、lifecycle invocation 与运行失败归属。"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from .base import FrameworkError
+
+if TYPE_CHECKING:
+    from ..diagnostics import LifecyclePhase, LifecycleStage, SourceLocation
+    from ..hosted_services.errors import HostedServiceLifecycleError
+    from ..lifecycle import ApplicationState
+    from ..modularity import ModuleKey
+    from .services import ContainerCleanupError
+
+
+class InvalidApplicationStateError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        operation: str,
+        current: ApplicationState,
+        allowed: tuple[ApplicationState, ...],
+    ) -> None:
+        self.operation = operation
+        self.current = current
+        self.allowed = allowed
+        allowed_values = ", ".join(state.value for state in allowed)
+        super().__init__(
+            f"Operation {operation!r} is invalid in state {current.value}; "
+            f"allowed: {allowed_values}"
+        )
+
+
+class CompositionResourceError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        module: ModuleKey,
+        stage: LifecycleStage,
+        resource_kind: str,
+    ) -> None:
+        self.module = module
+        self.stage = stage
+        self.resource_kind = resource_kind
+        super().__init__(
+            f"Composition hook {module}/{stage.value} returned forbidden {resource_kind}"
+        )
+
+
+class LifecycleReturnValueError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        module: ModuleKey,
+        phase: LifecyclePhase,
+        stage: LifecycleStage,
+        returned_type: str,
+    ) -> None:
+        self.module = module
+        self.phase = phase
+        self.stage = stage
+        self.returned_type = returned_type
+        super().__init__(
+            f"Lifecycle hook {module}/{stage.value} must return None, got {returned_type}"
+        )
+
+
+class LifecycleInvocationError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        failure_id: UUID,
+        module: ModuleKey,
+        phase: LifecyclePhase,
+        stage: LifecycleStage,
+        dependency_path: tuple[ModuleKey, ...],
+        duration_ns: int,
+        source: SourceLocation,
+        original_error: BaseException,
+    ) -> None:
+        self.failure_id = failure_id
+        self.module = module
+        self.phase = phase
+        self.stage = stage
+        self.dependency_path = dependency_path
+        self.duration_ns = duration_ns
+        self.source = source
+        # cleanup 为 best-effort 会收集 wrapper，因此构造时显式建立因果链。
+        self.__cause__ = original_error
+        self.__suppress_context__ = True
+        self.original_error = original_error
+        super().__init__(
+            f"Lifecycle invocation failed for {module}/{stage.value} "
+            f"with {type(original_error).__name__}"
+        )
+
+
+class _BackgroundExecutionStartFailure(FrameworkError):
+    """保留原始 background start failure，同时不伪造 Module lifecycle 位置。"""
+
+    failure_id = None
+    stage = None
+    dependency_path: tuple[ModuleKey, ...] = ()
+
+    def __init__(self, *, original_error: BaseException) -> None:
+        self.original_error = original_error
+        self.__cause__ = original_error
+        self.__suppress_context__ = True
+        super().__init__(f"Background execution start failed with {type(original_error).__name__}")
+
+
+class ApplicationRuntimeError(FrameworkError):
+    """运行期基础设施 fatal fact；不携带第三方异常正文或原始 cause。"""
+
+    def __init__(self, *, component: str, error_type: str) -> None:
+        self.component = component
+        self.error_type = error_type
+        # 标识一次失败事实，不持有原始异常、task 或 provider；同名失败仍是独立事实。
+        self._source = object()
+        super().__init__(f"Application runtime {component!r} failed with {error_type}")
+
+
+class ApplicationStartError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        primary: (
+            LifecycleInvocationError
+            | _BackgroundExecutionStartFailure
+            | HostedServiceLifecycleError
+        ),
+        cleanup_failures: tuple[
+            LifecycleInvocationError
+            | ContainerCleanupError
+            | _BackgroundExecutionStartFailure
+            | HostedServiceLifecycleError,
+            ...,
+        ],
+    ) -> None:
+        self.primary = primary
+        self.cleanup_failures = cleanup_failures
+        if isinstance(primary, LifecycleInvocationError):
+            location = f"{primary.module}/{primary.stage.value}"
+        elif isinstance(primary, _BackgroundExecutionStartFailure):
+            location = "background-execution"
+        else:
+            location = f"hosted-service:{primary.service}/{primary.operation}"
+        super().__init__(
+            f"Application start failed at {location}; cleanup failures: {len(cleanup_failures)}"
+        )
+
+
+def _exclude_runtime_failure(
+    error: BaseException, primary: ApplicationRuntimeError
+) -> BaseException | None:
+    # 发布 fatal 与观察 drain 可能竞争；终止 owner 才能确认哪个事实已成为主失败。
+    def same_source(item: BaseException) -> bool:
+        return isinstance(item, ApplicationRuntimeError) and item._source is primary._source
+
+    if isinstance(error, BaseExceptionGroup):
+        return error.split(same_source)[1]
+    return None if same_source(error) else error

python_platform/errors/modularity.py

@@ -0,0 +1,100 @@
+"""Module reference、graph 与 registry ownership 的结构化失败。"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import FrameworkError
+
+if TYPE_CHECKING:
+    from ..diagnostics import SourceLocation
+    from ..modularity import AppModule, ModuleDependencyEdge, ModuleKey
+
+
+class InvalidModuleReferenceError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        owner: ModuleKey | None,
+        reference: str,
+        reason: str,
+        source: SourceLocation | None,
+    ) -> None:
+        self.owner = owner
+        self.reference = reference
+        self.reason = reason
+        self.source = source
+        super().__init__(f"Invalid module reference {reference!r}: {reason}")
+
+
+class ModuleResolutionError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        owner: ModuleKey | None,
+        reference: str,
+        resolution_chain: tuple[str, ...],
+        source: SourceLocation | None,
+        original_error: BaseException,
+    ) -> None:
+        self.owner = owner
+        self.reference = reference
+        self.resolution_chain = resolution_chain
+        self.source = source
+        self.original_error = original_error
+        super().__init__(f"Unable to resolve module reference {reference!r}")
+
+
+class ModuleCycleError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        startup: ModuleKey,
+        path: tuple[ModuleKey, ...],
+        edges: tuple[ModuleDependencyEdge, ...],
+    ) -> None:
+        self.startup = startup
+        self.path = path
+        self.edges = edges
+        rendered_path = " -> ".join(str(key) for key in path)
+        super().__init__(f"Module dependency cycle: {rendered_path}")
+
+
+class GraphInvariantError(FrameworkError):
+    def __init__(self, detail: str) -> None:
+        self.detail = detail
+        super().__init__(f"Module graph invariant failed: {detail}")
+
+
+class DuplicateModuleIdentityError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        key: ModuleKey,
+        first_type: type[AppModule],
+        second_type: type[AppModule],
+    ) -> None:
+        self.key = key
+        self.first_type = first_type
+        self.second_type = second_type
+        super().__init__(f"Different module classes resolved to the same key {key}")
+
+
+class ModuleInstantiationError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        module: ModuleKey,
+        source: SourceLocation,
+        original_error: BaseException,
+    ) -> None:
+        self.module = module
+        self.source = source
+        self.original_error = original_error
+        super().__init__(f"Unable to instantiate module {module}")
+
+
+class UnknownModuleError(FrameworkError, KeyError):
+    def __init__(self, module: ModuleKey) -> None:
+        self.module = module
+        super().__init__(f"Unknown module {module}")

python_platform/errors/services.py

@@ -0,0 +1,100 @@
+"""Service composition、Convention 与 native container 的结构化失败。"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from .base import FrameworkError
+
+if TYPE_CHECKING:
+    from dishka import DependencyKey
+
+    from ..diagnostics import SourceLocation
+    from ..modularity import ModuleKey
+
+
+class InvalidConventionDefinitionError(FrameworkError):
+    def __init__(self, *, symbol: str, reason: str) -> None:
+        self.symbol = symbol
+        self.reason = reason
+        super().__init__(f"Invalid convention definition {symbol}: {reason}")
+
+
+class ConventionScanError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        owner: ModuleKey,
+        package: str | None,
+        source: SourceLocation,
+        reason: str,
+        original_error: BaseException | None,
+    ) -> None:
+        self.owner = owner
+        self.package = package
+        self.source = source
+        self.reason = reason
+        self.original_error = original_error
+        if original_error is not None:
+            self.__cause__ = original_error
+            self.__suppress_context__ = True
+        target = package if package is not None else "<invalid metadata>"
+        super().__init__(f"Convention scan failed for {owner}/{target}: {reason}")
+
+
+class ServiceContributorClosedError(FrameworkError):
+    def __init__(self, *, stage: str) -> None:
+        self.stage = stage
+        super().__init__(f"Service contributor is no longer active after {stage}")
+
+
+class RegistrationConflictError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        key: DependencyKey | None,
+        sources: tuple[SourceLocation, ...],
+        reason: str,
+    ) -> None:
+        self.key = key
+        self.sources = sources
+        self.reason = reason
+        rendered_key = str(key) if key is not None else "<provider>"
+        super().__init__(f"Service registration conflict for {rendered_key}: {reason}")
+
+
+class ContainerValidationError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        sources: tuple[SourceLocation, ...],
+        original_error: Exception,
+    ) -> None:
+        self.sources = sources
+        self.original_error = original_error
+        self.__cause__ = original_error
+        self.__suppress_context__ = True
+        super().__init__(
+            f"Dishka strict container validation failed with {type(original_error).__name__}"
+        )
+
+
+class CatalogNativeGraphMismatchError(FrameworkError):
+    def __init__(self, *, differences: tuple[str, ...]) -> None:
+        self.differences = differences
+        super().__init__(f"Service catalog/native graph mismatch: {len(differences)} difference(s)")
+
+
+class ContainerCleanupError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        failure_id: UUID,
+        original_error: BaseException,
+    ) -> None:
+        self.failure_id = failure_id
+        self.original_error = original_error
+        self.__cause__ = original_error
+        self.__suppress_context__ = True
+        super().__init__(f"Dishka container cleanup failed with {type(original_error).__name__}")

python_platform/events/__init__.py

@@ -0,0 +1,25 @@
+from .aggregate import AggregateEventCollector
+from .catalog import LocalEventCatalog, LocalEventSubscription
+from .contracts import LocalEventPhase, local_event_handler
+from .contribution import EventContributor
+from .errors import (
+    EventContributionError,
+    EventCycleError,
+    LocalEventHandlerError,
+    PostCommitEventError,
+)
+from .runtime import LocalEventBus
+
+__all__ = (
+    "AggregateEventCollector",
+    "EventContributionError",
+    "EventContributor",
+    "EventCycleError",
+    "LocalEventBus",
+    "LocalEventCatalog",
+    "LocalEventHandlerError",
+    "LocalEventPhase",
+    "LocalEventSubscription",
+    "PostCommitEventError",
+    "local_event_handler",
+)