python-platform 0.1.1__py3-none-any.whl

python_platform/application_services/policies.py

@@ -0,0 +1,46 @@
+"""实现声明的验证开关；静态 metadata 不保存调用状态。"""
+
+from __future__ import annotations
+
+from typing import TypeVar
+
+from .errors import ApplicationServiceDefinitionError
+
+_T = TypeVar("_T")
+_VALIDATION_ATTRIBUTE = "__python_platform_validation_enabled__"
+
+
+def _declare_switch(target: _T, attribute: str, enabled: bool) -> _T:
+    if not isinstance(target, type) and not callable(target):
+        raise ApplicationServiceDefinitionError(
+            symbol=str(type(target)), reason="policy requires a class or method"
+        )
+    if attribute in vars(target):
+        raise ApplicationServiceDefinitionError(
+            symbol=getattr(target, "__qualname__", "<policy>"), reason="policy is already declared"
+        )
+    setattr(target, attribute, enabled)
+    return target
+
+
+def disable_validation(target: _T) -> _T:
+    return _declare_switch(target, _VALIDATION_ATTRIBUTE, False)
+
+
+def enable_validation(target: _T) -> _T:
+    return _declare_switch(target, _VALIDATION_ATTRIBUTE, True)
+
+
+def _effective_switch(
+    implementation: type[object], method: object, attribute: str, default: bool
+) -> bool:
+    # 方法优先，再取 MRO 中最近的类声明；不把基类的禁用累加成无法恢复的开关。
+    for target in (method, *implementation.__mro__):
+        if attribute in vars(target):
+            value = vars(target)[attribute]
+            if not isinstance(value, bool):
+                raise ApplicationServiceDefinitionError(
+                    symbol=implementation.__qualname__, reason="policy metadata must be bool"
+                )
+            return value
+    return default

python_platform/application_services/seeding.py

@@ -0,0 +1,72 @@
+"""显式 Migration Host 使用的 ordered、per-contributor UoW seeding。"""
+
+from __future__ import annotations
+
+from abc import abstractmethod
+from typing import TYPE_CHECKING, cast
+
+from ..errors.base import FrameworkError
+from ..modularity import AppModule
+from ..modularity.selection import _dependency_keys
+from .contracts import _InternalApplicationServiceContributor
+
+if TYPE_CHECKING:
+    from ..application import Application
+
+
+class DataSeedContributor(_InternalApplicationServiceContributor):
+    """幂等性由具体 contributor 保证；框架只拥有顺序和独立 invocation。"""
+
+    @abstractmethod
+    async def seed(self) -> None:
+        raise NotImplementedError
+
+
+class DataSeedError(FrameworkError):
+    def __init__(
+        self,
+        *,
+        completed: tuple[type[DataSeedContributor], ...],
+        failed: type[DataSeedContributor],
+        original_error: BaseException,
+    ) -> None:
+        self.completed = completed
+        self.failed = failed
+        self.original_error = original_error
+        super().__init__(
+            f"Data seed contributor {failed.__module__}.{failed.__qualname__} failed after "
+            f"{len(completed)} completed contributor(s): {type(original_error).__name__}"
+        )
+
+
+class DataSeeder:
+    __slots__ = ("_application",)
+
+    def __init__(self, application: Application) -> None:
+        self._application = application
+
+    async def seed_all(
+        self, *, module: type[AppModule] | None = None
+    ) -> tuple[type[DataSeedContributor], ...]:
+        owners = _dependency_keys(self._application.modules, module) if module is not None else None
+        registrations = tuple(
+            registration
+            for registration in self._application.application_service_catalog.registrations
+            if issubclass(registration.implementation, DataSeedContributor)
+            and (owners is None or registration.implementation_owner in owners)
+        )
+        completed: list[type[DataSeedContributor]] = []
+        for registration in registrations:
+            contributor = cast(type[DataSeedContributor], registration.implementation)
+            # contributor 不发布 single Protocol，但仍复用同一 validation/UoW/event dispatcher。
+            try:
+                await self._application._invoke_registration(registration, "seed")
+            except Exception as original_error:
+                error = DataSeedError(
+                    completed=tuple(completed),
+                    failed=contributor,
+                    original_error=original_error,
+                )
+                raise error from original_error
+            completed.append(contributor)
+        return tuple(completed)

python_platform/application_services/signature.py

@@ -0,0 +1,49 @@
+"""业务签名比较保留 Pydantic 约束，把 FieldInfo 的 wire projection 与业务值分开。"""
+
+import inspect
+from copy import copy
+from typing import Annotated, Any, get_args, get_origin
+
+from pydantic.fields import FieldInfo
+from pydantic_core import PydanticUndefined
+
+
+def _business_annotation(annotation: Any) -> Any:
+    if get_origin(annotation) is not Annotated:
+        return annotation
+    base, *metadata = get_args(annotation)
+    constraints: list[object] = []
+    for item in metadata:
+        if isinstance(item, FieldInfo):
+            # Path(gt=...) 仍携带业务约束，不能整体丢掉 Annotated 或 FieldInfo。
+            constraints.extend(item.metadata)
+            for attribute in ("default_factory", "discriminator", "validate_default", "frozen"):
+                value = getattr(item, attribute)
+                if value is not None:
+                    constraints.append((attribute, value))
+            if item.default is not PydanticUndefined:
+                constraints.append(("default", item.default))
+        else:
+            constraints.append(item)
+    return (base, tuple(constraints)) if constraints else base
+
+
+def _business_signature(signature: inspect.Signature) -> inspect.Signature:
+    parameters = []
+    for parameter in signature.parameters.values():
+        default = parameter.default
+        annotation = parameter.annotation
+        if isinstance(default, FieldInfo):
+            binding = copy(default)
+            # 参数默认值由 Signature 比较，不能因 wire 声明的载体不同再比较一次。
+            binding.default = PydanticUndefined
+            annotation = Annotated[annotation, binding]
+            default = default.default
+            if default is PydanticUndefined:
+                default = inspect.Parameter.empty
+        parameters.append(
+            parameter.replace(annotation=_business_annotation(annotation), default=default)
+        )
+    return signature.replace(
+        parameters=parameters, return_annotation=_business_annotation(signature.return_annotation)
+    )

python_platform/application_services/validation.py

@@ -0,0 +1,84 @@
+"""Pydantic 调用参数边界与诊断脱敏；只保留静态签名允许的信息。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+from pydantic import ValidationError
+
+from .catalog import ApplicationServiceRegistration, _CompiledMethod
+from .errors import ApplicationServiceValidationError, ApplicationServiceValidationIssue
+
+
+async def _validate_arguments(
+    method: _CompiledMethod,
+    registration: ApplicationServiceRegistration,
+    args: tuple[object, ...],
+    kwargs: dict[str, object],
+) -> tuple[tuple[object, ...], dict[str, object]]:
+    validation_error: ApplicationServiceValidationError | None = None
+    try:
+        return await method.validator(None, *args, **kwargs)
+    except ValidationError as original_error:
+        validation_error = _sanitize_validation_error(
+            original_error,
+            registration=registration,
+            method_name=method.name,
+            parameter_names=method.parameter_names,
+        )
+    # 在 Pydantic except context 外抛出，避免 exception.__context__ 留住 raw input。
+    raise validation_error from None
+
+
+def _sanitize_validation_error(
+    error: ValidationError,
+    *,
+    registration: ApplicationServiceRegistration,
+    method_name: str,
+    parameter_names: frozenset[str],
+) -> ApplicationServiceValidationError:
+    issues = tuple(
+        ApplicationServiceValidationIssue(
+            location=_sanitize_validation_location(detail.get("loc"), parameter_names),
+            error_type=_sanitize_validation_error_type(detail),
+            # 自定义 Pydantic validator 的 msg/type 可能自行拼入原值；公开错误只保留静态事实。
+            message="Input validation failed",
+        )
+        for detail in error.errors(
+            include_url=True,
+            include_context=False,
+            include_input=False,
+        )
+    )
+    return ApplicationServiceValidationError(
+        service=registration.contract,
+        method_name=method_name,
+        issues=issues,
+    )
+
+
+def _sanitize_validation_location(
+    location: object,
+    parameter_names: frozenset[str],
+) -> tuple[str | int, ...]:
+    if not isinstance(location, tuple) or not location:
+        return ()
+    first = location[0]
+    if isinstance(first, str) and first in parameter_names:
+        return (first,)
+    if isinstance(first, int) and not isinstance(first, bool) and first >= 0:
+        return (first,)
+    return ()
+
+
+def _sanitize_validation_error_type(detail: Mapping[str, object]) -> str:
+    error_type = detail.get("type")
+    url = detail.get("url")
+    if (
+        isinstance(error_type, str)
+        and isinstance(url, str)
+        and url.startswith("https://errors.pydantic.dev/")
+        and url.endswith(f"/v/{error_type}")
+    ):
+        return error_type
+    return "value_error"

python_platform/auditing/__init__.py

@@ -0,0 +1,12 @@
+from .contracts import ApplicationServiceAuditRecord, AuditSink, RequestAuditRecord
+
+__all__ = (
+    "ApplicationServiceAuditRecord",
+    "AuditSink",
+    "AuditingControl",
+    "AuditingOptions",
+    "RequestAuditRecord",
+    "audited",
+    "disable_auditing",
+)
+from .control import AuditingControl, AuditingOptions, audited, disable_auditing

python_platform/auditing/contracts.py

@@ -0,0 +1,39 @@
+"""请求与 Application Service 审计只记录允许的静态事实。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Protocol
+from uuid import UUID
+
+
+@dataclass(frozen=True, slots=True)
+class RequestAuditRecord:
+    occurred_at: datetime
+    user_id: UUID | None
+    session_id: UUID | None
+    correlation_id: str
+    route_template: str
+    status_code: int
+    duration_ns: int
+    exception_type: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class ApplicationServiceAuditRecord:
+    occurred_at: datetime
+    user_id: UUID | None
+    session_id: UUID | None
+    correlation_id: str
+    contract: str
+    method: str
+    succeeded: bool
+    duration_ns: int
+    exception_type: str | None
+
+
+class AuditSink(Protocol):
+    async def write_request(self, record: RequestAuditRecord) -> None: ...
+
+    async def write_application_service(self, record: ApplicationServiceAuditRecord) -> None: ...

python_platform/auditing/control.py

@@ -0,0 +1,48 @@
+"""审计策略和 Application-local 运行时抑制；不改变外层请求审计。"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import TypeVar
+
+from pydantic import ConfigDict
+
+from ..application_services.policies import _declare_switch
+from ..options import BaseOptions
+
+_T = TypeVar("_T")
+_AUDITING_ATTRIBUTE = "__python_platform_auditing_enabled__"
+
+
+def disable_auditing(target: _T) -> _T:
+    return _declare_switch(target, _AUDITING_ATTRIBUTE, False)
+
+
+def audited(target: _T) -> _T:
+    return _declare_switch(target, _AUDITING_ATTRIBUTE, True)
+
+
+class AuditingOptions(BaseOptions):
+    model_config = ConfigDict(extra="forbid")
+    is_enabled: bool = True
+
+
+class AuditingControl:
+    """每个 Application 独立持有；只抑制当前异步上下文的方法审计。"""
+
+    def __init__(self) -> None:
+        self._disabled: ContextVar[bool] = ContextVar("method_auditing_disabled", default=False)
+
+    @property
+    def is_enabled(self) -> bool:
+        return not self._disabled.get()
+
+    @contextmanager
+    def disable(self) -> Iterator[None]:
+        token = self._disabled.set(True)
+        try:
+            yield
+        finally:
+            self._disabled.reset(token)

python_platform/auditing/sqlalchemy/__init__.py

@@ -0,0 +1,6 @@
+"""SQLAlchemy 审计持久化 provider。"""
+
+from .module import SqlAlchemyAuditingModule
+from .store import SqlAlchemyAuditSink
+
+__all__ = ("SqlAlchemyAuditSink", "SqlAlchemyAuditingModule")

python_platform/auditing/sqlalchemy/migrations/0001_platform_auditing.py

@@ -0,0 +1,45 @@
+"""Create the independent platform auditing migration branch."""
+
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "platform_auditing_0001"
+down_revision = None
+branch_labels = ("platform_auditing",)
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "platform_audit_logs",
+        sa.Column("audit_id", sa.Uuid(), nullable=False),
+        sa.Column("occurred_at", sa.DateTime(timezone=True), nullable=False),
+        sa.Column("kind", sa.String(length=32), nullable=False),
+        sa.Column("user_id", sa.Uuid(), nullable=True),
+        sa.Column("session_id", sa.Uuid(), nullable=True),
+        sa.Column("correlation_id", sa.String(length=128), nullable=False),
+        sa.Column("route_template", sa.String(length=512), nullable=True),
+        sa.Column("contract", sa.String(length=512), nullable=True),
+        sa.Column("method", sa.String(length=128), nullable=True),
+        sa.Column("status_code", sa.Integer(), nullable=True),
+        sa.Column("succeeded", sa.Boolean(), nullable=True),
+        sa.Column("duration_ns", sa.BigInteger(), nullable=False),
+        sa.Column("exception_type", sa.String(length=256), nullable=True),
+        sa.PrimaryKeyConstraint("audit_id"),
+    )
+    op.create_index("ix_platform_audit_logs_kind", "platform_audit_logs", ["kind"])
+    op.create_index("ix_platform_audit_logs_user_id", "platform_audit_logs", ["user_id"])
+    op.create_index(
+        "ix_platform_audit_logs_correlation_id",
+        "platform_audit_logs",
+        ["correlation_id"],
+    )
+
+
+def downgrade() -> None:
+    op.drop_index("ix_platform_audit_logs_correlation_id", table_name="platform_audit_logs")
+    op.drop_index("ix_platform_audit_logs_user_id", table_name="platform_audit_logs")
+    op.drop_index("ix_platform_audit_logs_kind", table_name="platform_audit_logs")
+    op.drop_table("platform_audit_logs")

python_platform/auditing/sqlalchemy/migrations/__init__.py

@@ -0,0 +1 @@
+"""Platform auditing Alembic branch。"""

python_platform/auditing/sqlalchemy/models.py

@@ -0,0 +1,31 @@
+"""审计日志的独立 metadata owner。"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from sqlalchemy import BigInteger, Boolean, DateTime, Integer, String, Uuid
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+
+
+class AuditingBase(DeclarativeBase):
+    pass
+
+
+class AuditLogRow(AuditingBase):
+    __tablename__ = "platform_audit_logs"
+
+    audit_id: Mapped[UUID] = mapped_column(Uuid, primary_key=True)
+    occurred_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), nullable=False)
+    kind: Mapped[str] = mapped_column(String(32), nullable=False, index=True)
+    user_id: Mapped[UUID | None] = mapped_column(Uuid, nullable=True, index=True)
+    session_id: Mapped[UUID | None] = mapped_column(Uuid, nullable=True)
+    correlation_id: Mapped[str] = mapped_column(String(128), nullable=False, index=True)
+    route_template: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    contract: Mapped[str | None] = mapped_column(String(512), nullable=True)
+    method: Mapped[str | None] = mapped_column(String(128), nullable=True)
+    status_code: Mapped[int | None] = mapped_column(Integer, nullable=True)
+    succeeded: Mapped[bool | None] = mapped_column(Boolean, nullable=True)
+    duration_ns: Mapped[int] = mapped_column(BigInteger, nullable=False)
+    exception_type: Mapped[str | None] = mapped_column(String(256), nullable=True)

python_platform/auditing/sqlalchemy/module.py

@@ -0,0 +1,32 @@
+"""Host 显式选择的 SQLAlchemy 审计 provider Module。"""
+
+from __future__ import annotations
+
+from dishka import Provider, Scope
+
+from ...lifecycle import ConfigureContext
+from ...modularity import AppModule
+from ...sqlalchemy import (
+    SqlAlchemyModelRegistration,
+    SqlAlchemyPersistenceModule,
+    contributes_sqlalchemy_models,
+)
+from ..contracts import AuditSink
+from .models import AuditingBase
+from .store import SqlAlchemyAuditSink
+
+
+@contributes_sqlalchemy_models(
+    SqlAlchemyModelRegistration(
+        metadata=AuditingBase.metadata,
+        migrations_package="python_platform.auditing.sqlalchemy.migrations",
+        branch_label="platform_auditing",
+    )
+)
+class SqlAlchemyAuditingModule(AppModule):
+    dependencies = (SqlAlchemyPersistenceModule,)
+
+    def configure(self, context: ConfigureContext) -> None:
+        provider = Provider()
+        provider.provide(SqlAlchemyAuditSink, provides=AuditSink, scope=Scope.APP)
+        context.services.contribute(provider, reason="SQLAlchemy independent audit sink")

python_platform/auditing/sqlalchemy/store.py

@@ -0,0 +1,63 @@
+"""每条审计记录使用独立短事务，不加入业务 Unit of Work。"""
+
+from __future__ import annotations
+
+from uuid import uuid4
+
+from ...sqlalchemy.auditing import PlatformAsyncSession
+from ...sqlalchemy.runtime import _SqlAlchemyEngineRegistry
+from ..contracts import ApplicationServiceAuditRecord, RequestAuditRecord
+from .models import AuditLogRow
+
+
+class SqlAlchemyAuditSink:
+    __slots__ = ("_engines",)
+
+    def __init__(self, engines: _SqlAlchemyEngineRegistry) -> None:
+        self._engines = engines
+
+    async def write_request(self, record: RequestAuditRecord) -> None:
+        await self._write(
+            AuditLogRow(
+                audit_id=uuid4(),
+                occurred_at=record.occurred_at,
+                kind="request",
+                user_id=record.user_id,
+                session_id=record.session_id,
+                correlation_id=record.correlation_id,
+                route_template=record.route_template,
+                contract=None,
+                method=None,
+                status_code=record.status_code,
+                succeeded=record.exception_type is None and record.status_code < 500,
+                duration_ns=record.duration_ns,
+                exception_type=record.exception_type,
+            )
+        )
+
+    async def write_application_service(self, record: ApplicationServiceAuditRecord) -> None:
+        await self._write(
+            AuditLogRow(
+                audit_id=uuid4(),
+                occurred_at=record.occurred_at,
+                kind="application_service",
+                user_id=record.user_id,
+                session_id=record.session_id,
+                correlation_id=record.correlation_id,
+                route_template=None,
+                contract=record.contract,
+                method=record.method,
+                status_code=None,
+                succeeded=record.succeeded,
+                duration_ns=record.duration_ns,
+                exception_type=record.exception_type,
+            )
+        )
+
+    async def _write(self, row: AuditLogRow) -> None:
+        async with PlatformAsyncSession(
+            self._engines.get("default"),
+            expire_on_commit=False,
+        ) as session:
+            async with session.begin():
+                session.add(row)

python_platform/authorization/__init__.py

@@ -0,0 +1,38 @@
+from .catalog import PermissionCatalog
+from .contracts import (
+    AccessTokenAuthenticator,
+    CurrentUser,
+    PermissionChecker,
+    PermissionDefinition,
+    PermissionName,
+    RolePermissionVersion,
+    allow_anonymous,
+    authorize,
+)
+from .definitions import PermissionDefinitionContext, PermissionDefinitionProvider
+from .errors import (
+    AuthorizationDefinitionError,
+    PermissionCheckerUnavailableError,
+    PermissionDefinitionError,
+    PermissionDeniedError,
+    UnauthenticatedError,
+)
+
+__all__ = (
+    "AccessTokenAuthenticator",
+    "AuthorizationDefinitionError",
+    "CurrentUser",
+    "PermissionCatalog",
+    "PermissionChecker",
+    "PermissionCheckerUnavailableError",
+    "PermissionDefinition",
+    "PermissionDefinitionContext",
+    "PermissionDefinitionError",
+    "PermissionDefinitionProvider",
+    "PermissionDeniedError",
+    "PermissionName",
+    "RolePermissionVersion",
+    "UnauthenticatedError",
+    "allow_anonymous",
+    "authorize",
+)

python_platform/authorization/catalog.py

@@ -0,0 +1,63 @@
+"""从 live Module metadata 聚合并冻结 Permission Catalog。"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Iterator, Mapping
+from types import MappingProxyType
+
+from ..modularity import ModuleRegistry
+from ..modularity.discovery import _DiscoveredType
+from .contracts import PermissionDefinition, PermissionName
+from .definition_discovery import _collect_permission_definitions
+from .errors import PermissionDefinitionError
+
+
+class PermissionCatalog:
+    __slots__ = ("_definitions", "_fingerprint")
+
+    def __init__(self, definitions: tuple[PermissionDefinition, ...]) -> None:
+        by_name: dict[PermissionName, PermissionDefinition] = {}
+        for definition in definitions:
+            if not isinstance(definition, PermissionDefinition):
+                raise PermissionDefinitionError(
+                    permission=repr(definition),
+                    reason="catalog entries must be PermissionDefinition values",
+                )
+            if definition.name in by_name:
+                raise PermissionDefinitionError(
+                    permission=str(definition.name),
+                    reason="permission is declared more than once",
+                )
+            by_name[definition.name] = definition
+        ordered = dict(sorted(by_name.items(), key=lambda item: item[0].value))
+        self._definitions: Mapping[PermissionName, PermissionDefinition] = MappingProxyType(ordered)
+        payload = tuple((item.name.value, item.display_name) for item in ordered.values())
+        self._fingerprint = hashlib.sha256(
+            json.dumps(payload, ensure_ascii=True, separators=(",", ":")).encode("utf-8")
+        ).hexdigest()
+
+    @property
+    def definitions(self) -> tuple[PermissionDefinition, ...]:
+        return tuple(self._definitions.values())
+
+    @property
+    def fingerprint(self) -> str:
+        return self._fingerprint
+
+    def __contains__(self, name: object) -> bool:
+        return name in self._definitions
+
+    def __iter__(self) -> Iterator[PermissionName]:
+        return iter(self._definitions)
+
+    def get(self, name: PermissionName) -> PermissionDefinition | None:
+        return self._definitions.get(name)
+
+
+def _build_permission_catalog(
+    registry: ModuleRegistry,
+    discoveries: tuple[_DiscoveredType, ...],
+) -> PermissionCatalog:
+    return PermissionCatalog(_collect_permission_definitions(registry, discoveries))