python-platform 0.1.1__py3-none-any.whl

python_platform/redis/runtime.py

@@ -0,0 +1,116 @@
+"""Application-owned Redis client lifecycle 与 typed JSON cache。"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import AsyncIterator
+from typing import Any
+
+from pydantic import ValidationError
+from redis.asyncio import Redis
+from redis.exceptions import RedisError
+
+from ..caching import CacheCatalog, CacheDefinition, DistributedCacheError
+from ..options import Options
+from .options import RedisOptions
+
+
+class _RedisClientOwner:
+    __slots__ = ("client",)
+
+    def __init__(self, client: Redis) -> None:
+        self.client = client
+
+    async def ping(self) -> None:
+        try:
+            await self.client.ping()
+        except RedisError as original_error:
+            raise DistributedCacheError(
+                operation="startup ping",
+                cache="redis",
+                error_type=type(original_error).__name__,
+            ) from None
+
+
+async def _redis_client(options: Options[RedisOptions]) -> AsyncIterator[_RedisClientOwner]:
+    client = Redis.from_url(options.value.url.get_secret_value(), decode_responses=False)
+    owner = _RedisClientOwner(client)
+    try:
+        yield owner
+    finally:
+        await client.aclose()
+
+
+class RedisDistributedCache:
+    __slots__ = ("_catalog", "_client", "_prefix")
+
+    def __init__(
+        self,
+        client: _RedisClientOwner,
+        catalog: CacheCatalog,
+        options: Options[RedisOptions],
+    ) -> None:
+        self._client = client.client
+        self._catalog = catalog
+        self._prefix = options.value.key_prefix
+
+    async def get(self, definition: CacheDefinition[Any], key: str) -> Any | None:
+        redis_key = self._key(definition, key)
+        try:
+            payload = await self._client.get(redis_key)
+            return None if payload is None else definition._deserialize(payload)
+        except (RedisError, TypeError, ValueError, ValidationError) as original_error:
+            raise DistributedCacheError(
+                operation="get",
+                cache=definition.name,
+                error_type=type(original_error).__name__,
+            ) from None
+
+    async def set(
+        self,
+        definition: CacheDefinition[Any],
+        key: str,
+        value: Any,
+    ) -> None:
+        redis_key = self._key(definition, key)
+        try:
+            payload = definition._serialize(value)
+            await self._client.set(redis_key, payload, ex=math.ceil(definition.ttl.total_seconds()))
+        except (RedisError, TypeError, ValueError, ValidationError) as original_error:
+            raise DistributedCacheError(
+                operation="set",
+                cache=definition.name,
+                error_type=type(original_error).__name__,
+            ) from None
+
+    async def remove(self, definition: CacheDefinition[Any], key: str) -> None:
+        redis_key = self._key(definition, key)
+        try:
+            await self._client.delete(redis_key)
+        except RedisError as original_error:
+            raise DistributedCacheError(
+                operation="remove",
+                cache=definition.name,
+                error_type=type(original_error).__name__,
+            ) from None
+
+    def _key(self, definition: CacheDefinition[Any], key: str) -> str:
+        if not self._catalog.owns(definition):
+            raise DistributedCacheError(
+                operation="key",
+                cache=definition.name,
+                error_type="ForeignCacheDefinition",
+            )
+        if (
+            not isinstance(key, str)
+            or not key
+            or key != key.strip()
+            or any(character.isspace() for character in key)
+            or len(key) > 512
+        ):
+            raise DistributedCacheError(
+                operation="key",
+                cache=definition.name,
+                error_type="InvalidCacheKey",
+            )
+        return f"{self._prefix}:{definition.name}:{key}"

python_platform/services/__init__.py

@@ -0,0 +1,39 @@
+"""Service composition public contracts and Application-internal owners."""
+
+from .contribution import ServiceContributor
+from .convention_contracts import (
+    ConventionalService,
+    ConventionCandidate,
+    ConventionCandidateDecision,
+    ConventionDiscoveryKind,
+    ScopedDependency,
+    SingletonDependency,
+    TransientDependency,
+    service,
+)
+from .registration import (
+    ProviderContribution,
+    ProviderContributionView,
+    RegistrationDecision,
+    RegistrationKind,
+    ServiceCatalog,
+    ServiceRegistration,
+)
+
+__all__ = (
+    "ConventionCandidate",
+    "ConventionCandidateDecision",
+    "ConventionDiscoveryKind",
+    "ConventionalService",
+    "ProviderContribution",
+    "ProviderContributionView",
+    "RegistrationDecision",
+    "RegistrationKind",
+    "ScopedDependency",
+    "ServiceCatalog",
+    "ServiceContributor",
+    "ServiceRegistration",
+    "SingletonDependency",
+    "TransientDependency",
+    "service",
+)

python_platform/services/application_bindings.py

@@ -0,0 +1,221 @@
+"""应用服务绑定与 provider 重定位；依赖既有 DI 仲裁结果，不重复仲裁。"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from dishka import (
+    DEFAULT_COMPONENT,
+    DependencyKey,
+    Provider,
+    Scope,
+)
+
+from ..application_services import ApplicationService
+from ..application_services.catalog import (
+    _APPLICATION_SERVICE_COMPONENT,
+    _ApplicationServiceBinding,
+    _DiscoveredApplicationService,
+)
+from ..application_services.errors import ApplicationServiceDefinitionError
+from ..diagnostics import SourceLocation
+from ..modularity import ModuleRegistry
+from .arbitration import (
+    _ArbitrationResult,
+    _provider_with_active_sources,
+    _RegistrationDraft,
+)
+from .registration import (
+    RegistrationDecision,
+    RegistrationKind,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class _BoundApplicationService:
+    binding: _ApplicationServiceBinding
+    winner: _RegistrationDraft
+    related_draft_ids: frozenset[int]
+
+
+def _bind_application_services(
+    discoveries: tuple[_DiscoveredApplicationService, ...],
+    drafts: tuple[_RegistrationDraft, ...],
+) -> tuple[_BoundApplicationService, ...]:
+    """把扫描声明关联到既有 DI 仲裁 winner，不再维护第二套 override 规则。"""
+
+    bound: list[_BoundApplicationService] = []
+    for discovery in discoveries:
+        contract = discovery.definition.contract or discovery.service_type
+        public_key = DependencyKey(contract, DEFAULT_COMPONENT)
+        declaration = tuple(
+            draft
+            for draft in drafts
+            if draft.factory is not None
+            and draft.factory.source is discovery.service_type
+            and draft.key == public_key
+            and draft.contribution.kind is RegistrationKind.CONVENTION
+        )
+        if len(declaration) != 1:
+            raise ApplicationServiceDefinitionError(
+                symbol=(
+                    f"{discovery.service_type.__module__}.{discovery.service_type.__qualname__}"
+                ),
+                reason="decorated implementation must own one convention binding for its contract",
+            )
+        # contract key 的全部 draft 都属于同一 provenance chain，Catalog 记录最终事实与被替换来源。
+        related = tuple(
+            draft for draft in drafts if not draft.is_collection and draft.key == public_key
+        )
+        winners = tuple(
+            draft for draft in related if draft.decision is RegistrationDecision.ACCEPTED
+        )
+        if len(winners) != 1:
+            raise ApplicationServiceDefinitionError(
+                symbol=f"{contract.__module__}.{contract.__qualname__}",
+                reason="application service contract must have one accepted DI implementation",
+            )
+        winner = winners[0]
+        if winner.scope is not Scope.ACTION or winner.factory is None:
+            raise ApplicationServiceDefinitionError(
+                symbol=f"{contract.__module__}.{contract.__qualname__}",
+                reason="final application service implementation must remain ACTION scoped",
+            )
+        implementation = winner.factory.source
+        if not isinstance(implementation, type) or not issubclass(
+            implementation,
+            ApplicationService,
+        ):
+            raise ApplicationServiceDefinitionError(
+                symbol=f"{contract.__module__}.{contract.__qualname__}",
+                reason=(
+                    "final application service binding must use an ApplicationService class factory"
+                ),
+            )
+        replaced_sources: list[SourceLocation] = []
+        for draft in related:
+            if draft is winner:
+                continue
+            source = draft.contribution.source
+            if source not in replaced_sources:
+                replaced_sources.append(source)
+        bound.append(
+            _BoundApplicationService(
+                binding=_ApplicationServiceBinding(
+                    discovery=discovery,
+                    implementation=implementation,
+                    implementation_owner=winner.contribution.owner,
+                    implementation_source=winner.contribution.source,
+                    replaced_sources=tuple(replaced_sources),
+                ),
+                winner=winner,
+                related_draft_ids=frozenset(id(draft) for draft in related),
+            )
+        )
+    return tuple(bound)
+
+
+def _validate_application_service_dependencies(
+    registry: ModuleRegistry,
+    services: tuple[_BoundApplicationService, ...],
+    drafts: tuple[_RegistrationDraft, ...],
+) -> None:
+    contracts = {
+        DependencyKey(
+            item.binding.discovery.definition.contract or item.binding.discovery.service_type,
+            DEFAULT_COMPONENT,
+        ): item.binding.discovery.owner
+        for item in services
+    }
+    bound_ids = {draft_id for item in services for draft_id in item.related_draft_ids}
+    for draft in drafts:
+        if draft.decision is not RegistrationDecision.ACCEPTED or draft.factory is None:
+            continue
+        factory = draft.factory
+        publishes_implementation = any(
+            isinstance(candidate, type) and issubclass(candidate, ApplicationService)
+            for candidate in (factory.source, draft.key.type_hint)
+        )
+        if publishes_implementation and id(draft) not in bound_ids:
+            raise ApplicationServiceDefinitionError(
+                symbol=str(draft.key.type_hint),
+                reason="ApplicationService cannot publish an unmanaged implementation binding",
+            )
+        visible = {draft.contribution.owner}
+        pending = [draft.contribution.owner]
+        while pending:
+            for dependency in registry.descriptors[pending.pop()].dependencies:
+                if dependency not in visible:
+                    visible.add(dependency)
+                    pending.append(dependency)
+        for key in (*factory.dependencies, *factory.kw_dependencies.values()):
+            dependency_key = (
+                key.with_component(draft.key.component) if key.component is None else key
+            )
+            owner = contracts.get(dependency_key)
+            if owner is not None and owner not in visible:
+                raise ApplicationServiceDefinitionError(
+                    symbol=str(draft.key.type_hint),
+                    reason=f"service dependency requires a declared Module dependency on {owner}",
+                )
+
+
+def _runtime_providers(
+    arbitration: _ArbitrationResult,
+    services: tuple[_BoundApplicationService, ...],
+) -> tuple[Provider, ...]:
+    """仅重定位 Application Service factories；其他 Dishka provider 保持原生形状。"""
+
+    related_draft_ids = frozenset(
+        draft_id for service in services for draft_id in service.related_draft_ids
+    )
+    drafts_by_entry: dict[int, list[_RegistrationDraft]] = {}
+    for draft in arbitration.drafts:
+        drafts_by_entry.setdefault(draft.entry.entry_id, []).append(draft)
+
+    providers: list[Provider] = []
+    for entry in arbitration.ordered_entries:
+        entry_drafts = drafts_by_entry[entry.entry_id]
+        active = tuple(
+            draft
+            for draft in entry_drafts
+            if draft.decision is not RegistrationDecision.BACKED_OFF
+            and id(draft) not in related_draft_ids
+        )
+        if not active:
+            continue
+        if len(active) == len(entry_drafts):
+            providers.append(entry.contribution.provider)
+        else:
+            providers.append(_provider_with_active_sources(entry.contribution.provider, active))
+
+    # default component 只发布 REQUEST proxy；ACTION implementation 统一藏入框架私有 component。
+    implementation_provider = Provider(component=_APPLICATION_SERVICE_COMPONENT)
+    for service in services:
+        winner = service.winner
+        assert winner.factory is not None
+        # internal contributor 被 override 时仍以原声明 key 调度；
+        # winner class 只是实现事实，不能改写契约 key。
+        contract = (
+            service.binding.discovery.definition.contract or service.binding.discovery.service_type
+        )
+        implementation_provider.factories.append(
+            winner.factory.replace(
+                dependencies=tuple(
+                    dependency.with_component(DEFAULT_COMPONENT)
+                    for dependency in winner.factory.dependencies
+                ),
+                kw_dependencies={
+                    name: dependency.with_component(DEFAULT_COMPONENT)
+                    for name, dependency in winner.factory.kw_dependencies.items()
+                },
+                provides=DependencyKey(contract, None),
+                when_override=None,
+                when_component=DEFAULT_COMPONENT,
+            )
+        )
+        # ServiceCatalog 的 accepted row 必须描述 relocated native binding，而非旧 default key。
+        winner.key = DependencyKey(contract, _APPLICATION_SERVICE_COMPONENT)
+    if services:
+        providers.append(implementation_provider)
+    return tuple(providers)