python-platform 0.1.1__py3-none-any.whl

python_platform/modularity/contracts.py

@@ -0,0 +1,90 @@
+"""Module declaration、identity 与显式 dependency contracts。"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import TYPE_CHECKING, Any, ClassVar, TypeAlias
+
+from ..diagnostics import SourceLocation
+
+if TYPE_CHECKING:
+    from ..background_jobs import BackgroundJobDefinition, BackgroundJobSchedule
+    from ..background_workers import BackgroundWorkerDefinition
+    from ..caching import CacheDefinition
+    from ..hosted_services import HostedService
+    from ..lifecycle import (
+        ConfigureContext,
+        InitializeContext,
+        PostConfigureContext,
+        PostInitializeContext,
+        PreConfigureContext,
+        PreInitializeContext,
+        ShutdownContext,
+    )
+    from ..notifications import NotificationDefinition
+    from ..settings.handlers import SettingHandlerDefinition
+
+
+@dataclass(frozen=True, slots=True)
+class ModuleRef:
+    target: str
+
+
+@dataclass(frozen=True, order=True, slots=True)
+class ModuleKey:
+    module: str
+    qualname: str
+
+    def __str__(self) -> str:
+        return f"{self.module}:{self.qualname}"
+
+
+@dataclass(frozen=True, slots=True)
+class ModuleDependencyEdge:
+    """保留一次显式依赖声明的原始引用与 owner source。"""
+
+    owner: ModuleKey
+    dependency: ModuleKey
+    reference: str
+    source: SourceLocation
+
+
+class AppModule:
+    """模块 Template Method；每次 Application build 都创建独立实例。"""
+
+    dependencies: ClassVar[tuple[type[AppModule] | ModuleRef, ...]] = ()
+    scan_packages: ClassVar[tuple[str, ...]] = ()
+    configuration_defaults: ClassVar[Mapping[str, object]] = MappingProxyType({})
+    cache_definitions: ClassVar[tuple[CacheDefinition[Any], ...]] = ()
+    setting_handler_definitions: ClassVar[tuple[SettingHandlerDefinition[Any], ...]] = ()
+    notification_definitions: ClassVar[tuple[NotificationDefinition[Any], ...]] = ()
+    background_worker_definitions: ClassVar[tuple[BackgroundWorkerDefinition, ...]] = ()
+    background_job_definitions: ClassVar[tuple[BackgroundJobDefinition[Any], ...]] = ()
+    background_job_schedules: ClassVar[tuple[BackgroundJobSchedule, ...]] = ()
+    hosted_services: ClassVar[tuple[type[HostedService], ...]] = ()
+
+    def pre_configure(self, context: PreConfigureContext) -> None:
+        pass
+
+    def configure(self, context: ConfigureContext) -> None:
+        pass
+
+    def post_configure(self, context: PostConfigureContext) -> None:
+        pass
+
+    async def pre_initialize(self, context: PreInitializeContext) -> None:
+        pass
+
+    async def initialize(self, context: InitializeContext) -> None:
+        pass
+
+    async def post_initialize(self, context: PostInitializeContext) -> None:
+        pass
+
+    async def shutdown(self, context: ShutdownContext) -> None:
+        pass
+
+
+ModuleDependency: TypeAlias = type[AppModule] | ModuleRef

python_platform/modularity/discovery.py

@@ -0,0 +1,143 @@
+"""冻结 Module 扫描范围的类型发现；能力解释复用同一 Application-local 结果。"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+import pkgutil
+from collections.abc import Mapping
+from dataclasses import dataclass
+from types import MappingProxyType, ModuleType
+
+from ..diagnostics import SourceLocation
+from ..errors import ConventionScanError
+from .contracts import ModuleKey
+from .registry import ModuleDescriptor, ModuleRegistry
+
+
+@dataclass(frozen=True, slots=True)
+class _DiscoveredType:
+    owner: ModuleKey
+    package: str
+    candidate: type[object]
+    source: SourceLocation
+
+
+def _discover_types(
+    registry: ModuleRegistry, packages: Mapping[ModuleKey, tuple[str, ...]]
+) -> tuple[_DiscoveredType, ...]:
+    return tuple(
+        _DiscoveredType(
+            descriptor.key, package, candidate, _class_source(candidate, descriptor.key)
+        )
+        for descriptor in registry.dependency_order
+        for package in packages[descriptor.key]
+        for module in _import_modules(descriptor, package)
+        for candidate in _module_candidates(module)
+    )
+
+
+def _import_modules(
+    descriptor: ModuleDescriptor,
+    package_name: str,
+) -> tuple[ModuleType, ...]:
+    try:
+        root = importlib.import_module(package_name)
+        module_names = {root.__name__}
+        package_path = getattr(root, "__path__", None)
+        if package_path is not None:
+            module_names.update(
+                item.name
+                for item in pkgutil.walk_packages(
+                    package_path,
+                    f"{root.__name__}.",
+                    onerror=_raise_scan_import_error,
+                )
+            )
+        return tuple(importlib.import_module(name) for name in sorted(module_names))
+    except Exception as original_error:
+        error = ConventionScanError(
+            owner=descriptor.key,
+            package=package_name,
+            source=descriptor.declaration_source,
+            reason="unable to import controlled convention scan package",
+            original_error=original_error,
+        )
+        raise error from original_error
+
+
+def _module_candidates(module: ModuleType) -> tuple[type[object], ...]:
+    return tuple(
+        value
+        for value in vars(module).values()
+        if isinstance(value, type) and value.__module__ == module.__name__
+    )
+
+
+def _class_source(candidate: type[object], owner: ModuleKey) -> SourceLocation:
+    file_name: str | None = None
+    line: int | None = None
+    try:
+        file_name = inspect.getsourcefile(candidate)
+        _, line = inspect.getsourcelines(candidate)
+    except (OSError, TypeError):
+        pass
+    return SourceLocation(
+        owner=str(owner),
+        file=file_name,
+        line=line,
+        symbol=f"{candidate.__module__}.{candidate.__qualname__}",
+    )
+
+
+def _raise_scan_import_error(module_name: str) -> None:
+    raise ImportError(f"unable to import convention scan package {module_name}")
+
+
+def _snapshot_scan_packages(
+    registry: ModuleRegistry,
+) -> Mapping[ModuleKey, tuple[str, ...]]:
+    snapshots = {
+        descriptor.key: _validate_scan_packages(descriptor)
+        for descriptor in registry.dependency_order
+    }
+    return MappingProxyType(snapshots)
+
+
+def _validate_scan_packages(descriptor: ModuleDescriptor) -> tuple[str, ...]:
+    packages = descriptor.module_type.scan_packages
+    if not isinstance(packages, tuple):
+        raise ConventionScanError(
+            owner=descriptor.key,
+            package=None,
+            source=descriptor.declaration_source,
+            reason="scan_packages metadata must be an immutable tuple",
+            original_error=None,
+        )
+    seen: set[str] = set()
+    snapshot: list[str] = []
+    for package in packages:
+        if (
+            not isinstance(package, str)
+            or not package
+            or any(not segment.isidentifier() for segment in package.split("."))
+        ):
+            raise ConventionScanError(
+                owner=descriptor.key,
+                package=package if isinstance(package, str) else None,
+                source=descriptor.declaration_source,
+                reason="scan package must be a dotted Python module name",
+                original_error=None,
+            )
+        if package in seen:
+            raise ConventionScanError(
+                owner=descriptor.key,
+                package=package,
+                source=descriptor.declaration_source,
+                reason="scan package is declared more than once",
+                original_error=None,
+            )
+        seen.add(package)
+        snapshot.append(package)
+    # 不保留 Module class attribute 的 tuple identity，快照只归当前 build 所有。
+    return tuple(snapshot)

python_platform/modularity/graph.py

@@ -0,0 +1,334 @@
+"""Module reference resolution、graph validation 与 instance construction。"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+from collections.abc import Mapping
+from graphlib import CycleError, TopologicalSorter
+from itertools import pairwise
+from typing import TypeGuard
+
+from ..diagnostics import SourceLocation
+from ..errors import (
+    DuplicateModuleIdentityError,
+    GraphInvariantError,
+    InvalidModuleReferenceError,
+    ModuleCycleError,
+    ModuleInstantiationError,
+    ModuleResolutionError,
+)
+from .contracts import AppModule, ModuleDependency, ModuleDependencyEdge, ModuleKey, ModuleRef
+from .registry import ModuleDescriptor, ModuleRegistry
+
+
+class _ModuleGraphBuilder:
+    """拥有一次 graph discovery 的全部 mutable state，成功后只发布 immutable registry。"""
+
+    __slots__ = (
+        "_dependency_edges",
+        "_dependency_paths",
+        "_discovery_indices",
+        "_module_types",
+        "_predecessors",
+        "_sources",
+        "_startup",
+    )
+
+    def __init__(self, startup: type[AppModule] | ModuleRef) -> None:
+        self._startup = startup
+        self._module_types: dict[ModuleKey, type[AppModule]] = {}
+        self._discovery_indices: dict[ModuleKey, int] = {}
+        self._predecessors: dict[ModuleKey, tuple[ModuleKey, ...]] = {}
+        self._dependency_paths: dict[ModuleKey, tuple[ModuleKey, ...]] = {}
+        self._dependency_edges: dict[tuple[ModuleKey, ModuleKey], ModuleDependencyEdge] = {}
+        self._sources: dict[ModuleKey, SourceLocation] = {}
+
+    def build(self) -> ModuleRegistry:
+        startup_type, startup_key = self._resolve_module(
+            self._startup, owner=None, owner_source=None, resolution_chain=()
+        )
+        self._discover(startup_type, startup_key, (), ())
+        dependency_keys = self._stable_dependency_order(startup_key)
+        instances = self._instantiate(dependency_keys)
+        descriptors = {
+            key: ModuleDescriptor(
+                key=key,
+                module_type=self._module_types[key],
+                instance=instances[key],
+                dependencies=self._predecessors[key],
+                dependency_path=self._dependency_paths[key],
+                dependency_edges=tuple(
+                    self._dependency_edges[(key, dependency)]
+                    for dependency in self._predecessors[key]
+                ),
+                discovery_index=self._discovery_indices[key],
+                declaration_source=self._sources[key],
+            )
+            for key in dependency_keys
+        }
+        dependency_order = tuple(descriptors[key] for key in dependency_keys)
+        return ModuleRegistry(
+            startup=descriptors[startup_key],
+            descriptors=descriptors,
+            dependency_order=dependency_order,
+        )
+
+    def _discover(
+        self,
+        module_type: type[AppModule],
+        key: ModuleKey,
+        resolution_chain: tuple[str, ...],
+        owner_path: tuple[ModuleKey, ...],
+    ) -> None:
+        existing = self._module_types.get(key)
+        if existing is not None:
+            if existing is not module_type:
+                raise DuplicateModuleIdentityError(
+                    key=key, first_type=existing, second_type=module_type
+                )
+            return
+
+        self._module_types[key] = module_type
+        self._discovery_indices[key] = len(self._discovery_indices)
+        self._dependency_paths[key] = (*owner_path, key)
+        source = self._module_source(module_type, key)
+        self._sources[key] = source
+
+        declared_dependencies = module_type.dependencies
+        if not isinstance(declared_dependencies, tuple):
+            raise InvalidModuleReferenceError(
+                owner=key,
+                reference=type(declared_dependencies).__name__,
+                reason="dependencies metadata must be an immutable tuple",
+                source=source,
+            )
+
+        normalized_dependencies: list[ModuleKey] = []
+        seen_dependencies: set[ModuleKey] = set()
+        child_chain = (*resolution_chain, str(key))
+        for dependency in declared_dependencies:
+            dependency_type, dependency_key = self._resolve_module(
+                dependency,
+                owner=key,
+                owner_source=source,
+                resolution_chain=child_chain,
+            )
+            if dependency_key not in seen_dependencies:
+                normalized_dependencies.append(dependency_key)
+                seen_dependencies.add(dependency_key)
+                self._dependency_edges[(key, dependency_key)] = ModuleDependencyEdge(
+                    owner=key,
+                    dependency=dependency_key,
+                    reference=self._dependency_reference(dependency, dependency_key),
+                    source=source,
+                )
+            self._discover(
+                dependency_type,
+                dependency_key,
+                child_chain,
+                self._dependency_paths[key],
+            )
+        self._predecessors[key] = tuple(normalized_dependencies)
+
+    def _instantiate(self, dependency_keys: tuple[ModuleKey, ...]) -> dict[ModuleKey, AppModule]:
+        # graph 完整验证后才实例化，constructor 失败也不会触发 lifecycle hook。
+        instances: dict[ModuleKey, AppModule] = {}
+        for key in dependency_keys:
+            module_type = self._module_types[key]
+            try:
+                instance = module_type()
+            except Exception as original_error:
+                error = ModuleInstantiationError(
+                    module=key,
+                    source=self._sources[key],
+                    original_error=original_error,
+                )
+                raise error from original_error
+            instances[key] = instance
+        return instances
+
+    def _stable_dependency_order(self, startup: ModuleKey) -> tuple[ModuleKey, ...]:
+        sorter: TopologicalSorter[ModuleKey] = TopologicalSorter(self._predecessors)
+        try:
+            sorter.prepare()
+        except CycleError as cycle_error:
+            raw_path = self._cycle_from_error(cycle_error)
+            path = self._normalize_cycle(raw_path)
+            try:
+                edges = tuple(
+                    self._dependency_edges[(owner, dependency)]
+                    for owner, dependency in pairwise(path)
+                )
+            except KeyError as missing_edge:
+                raise GraphInvariantError(
+                    "cycle path had no matching dependency edge"
+                ) from missing_edge
+            raise ModuleCycleError(startup=startup, path=path, edges=edges) from cycle_error
+
+        order: list[ModuleKey] = []
+        while sorter.is_active():
+            ready = tuple(sorted(sorter.get_ready(), key=self._discovery_indices.__getitem__))
+            order.extend(ready)
+            sorter.done(*ready)
+        positions = {key: index for index, key in enumerate(order)}
+        for owner, dependencies in self._predecessors.items():
+            if any(positions[dependency] >= positions[owner] for dependency in dependencies):
+                raise GraphInvariantError("dependency order placed an owner before its dependency")
+        return tuple(order)
+
+    def _normalize_cycle(self, raw_path: tuple[ModuleKey, ...]) -> tuple[ModuleKey, ...]:
+        # graphlib 报告 predecessor 方向；公开错误固定为 owner -> declared dependency 方向。
+        candidates = (raw_path, tuple(reversed(raw_path)))
+        declared_path = next(
+            (
+                candidate
+                for candidate in candidates
+                if self._follows_declarations(candidate, self._predecessors)
+            ),
+            None,
+        )
+        if declared_path is None:
+            raise GraphInvariantError(
+                "cycle direction could not be matched to dependency declarations"
+            )
+        open_path = declared_path[:-1]
+        start_index = min(
+            range(len(open_path)), key=lambda index: self._discovery_indices[open_path[index]]
+        )
+        rotated = open_path[start_index:] + open_path[:start_index]
+        return (*rotated, rotated[0])
+
+    @staticmethod
+    def _module_key(module_type: type[AppModule]) -> ModuleKey:
+        return ModuleKey(module=module_type.__module__, qualname=module_type.__qualname__)
+
+    @staticmethod
+    def _module_source(module_type: type[AppModule], key: ModuleKey) -> SourceLocation:
+        file_name: str | None = None
+        line: int | None = None
+        try:
+            file_name = inspect.getsourcefile(module_type)
+            _, line = inspect.getsourcelines(module_type)
+        except (OSError, TypeError):
+            pass
+        return SourceLocation(str(key), file_name, line, module_type.__qualname__)
+
+    @staticmethod
+    def _is_module_type(value: object) -> TypeGuard[type[AppModule]]:
+        return isinstance(value, type) and issubclass(value, AppModule)
+
+    @classmethod
+    def _resolve_module(
+        cls,
+        dependency: object,
+        *,
+        owner: ModuleKey | None,
+        owner_source: SourceLocation | None,
+        resolution_chain: tuple[str, ...],
+    ) -> tuple[type[AppModule], ModuleKey]:
+        # 动态 import 是不可信边界；收窄为 AppModule type 后图算法不再重复猜测类型。
+        if cls._is_module_type(dependency):
+            return dependency, cls._module_key(dependency)
+        if not isinstance(dependency, ModuleRef):
+            raise InvalidModuleReferenceError(
+                owner=owner,
+                reference=type(dependency).__name__,
+                reason="dependency must be an AppModule type or ModuleRef",
+                source=owner_source,
+            )
+        module_name, qualname = cls._parse_module_ref(
+            dependency.target, owner=owner, owner_source=owner_source
+        )
+        try:
+            resolved: object = importlib.import_module(module_name)
+            for part in qualname.split("."):
+                resolved = getattr(resolved, part)
+        except Exception as original_error:
+            error = ModuleResolutionError(
+                owner=owner,
+                reference=dependency.target,
+                resolution_chain=(*resolution_chain, dependency.target),
+                source=owner_source,
+                original_error=original_error,
+            )
+            raise error from original_error
+        if not cls._is_module_type(resolved):
+            raise InvalidModuleReferenceError(
+                owner=owner,
+                reference=dependency.target,
+                reason="resolved target must be an AppModule class",
+                source=owner_source,
+            )
+        return resolved, cls._module_key(resolved)
+
+    @staticmethod
+    def _parse_module_ref(
+        target: object,
+        *,
+        owner: ModuleKey | None,
+        owner_source: SourceLocation | None,
+    ) -> tuple[str, str]:
+        if not isinstance(target, str):
+            raise InvalidModuleReferenceError(
+                owner=owner,
+                reference=type(target).__name__,
+                reason="ModuleRef.target must be a string",
+                source=owner_source,
+            )
+        if target.count(":") != 1:
+            raise InvalidModuleReferenceError(
+                owner=owner,
+                reference=target,
+                reason="target must contain exactly one ':' separator",
+                source=owner_source,
+            )
+        module_name, qualname = target.split(":")
+        if not module_name or not qualname:
+            raise InvalidModuleReferenceError(
+                owner=owner,
+                reference=target,
+                reason="module and qualified name must both be non-empty",
+                source=owner_source,
+            )
+        if any(not part.isidentifier() for part in module_name.split(".")):
+            raise InvalidModuleReferenceError(
+                owner=owner,
+                reference=target,
+                reason="each module-name segment must be a Python identifier",
+                source=owner_source,
+            )
+        if any(not part.isidentifier() for part in qualname.split(".")):
+            raise InvalidModuleReferenceError(
+                owner=owner,
+                reference=target,
+                reason="each qualified-name segment must be a Python identifier",
+                source=owner_source,
+            )
+        return module_name, qualname
+
+    @staticmethod
+    def _dependency_reference(dependency: ModuleDependency, dependency_key: ModuleKey) -> str:
+        return dependency.target if isinstance(dependency, ModuleRef) else str(dependency_key)
+
+    @staticmethod
+    def _cycle_from_error(error: CycleError) -> tuple[ModuleKey, ...]:
+        if len(error.args) < 2 or not isinstance(error.args[1], (list, tuple)):
+            raise GraphInvariantError("graphlib did not provide a cycle path") from error
+        nodes: list[ModuleKey] = []
+        for item in error.args[1]:
+            if not isinstance(item, ModuleKey):
+                raise GraphInvariantError(
+                    "graphlib cycle contained a non-ModuleKey node"
+                ) from error
+            nodes.append(item)
+        if len(nodes) < 2 or nodes[0] != nodes[-1]:
+            raise GraphInvariantError("graphlib cycle path was not closed") from error
+        return tuple(nodes)
+
+    @staticmethod
+    def _follows_declarations(
+        path: tuple[ModuleKey, ...],
+        predecessors: Mapping[ModuleKey, tuple[ModuleKey, ...]],
+    ) -> bool:
+        return all(path[index + 1] in predecessors[path[index]] for index in range(len(path) - 1))

python_platform/modularity/registry.py

@@ -0,0 +1,100 @@
+"""单个 Application 的不可变 Module registry 与 graph snapshot。"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass
+from types import MappingProxyType
+
+from ..diagnostics import SourceLocation
+from ..errors import UnknownModuleError
+from .contracts import AppModule, ModuleDependencyEdge, ModuleKey
+
+
+@dataclass(frozen=True, slots=True)
+class ModuleDescriptor:
+    key: ModuleKey
+    module_type: type[AppModule]
+    instance: AppModule
+    dependencies: tuple[ModuleKey, ...]
+    dependency_path: tuple[ModuleKey, ...]
+    dependency_edges: tuple[ModuleDependencyEdge, ...]
+    discovery_index: int
+    declaration_source: SourceLocation
+
+
+@dataclass(frozen=True, slots=True)
+class ModuleGraphSnapshot:
+    startup: ModuleKey
+    dependencies: Mapping[ModuleKey, tuple[ModuleKey, ...]]
+    dependency_paths: Mapping[ModuleKey, tuple[ModuleKey, ...]]
+    dependency_edges: tuple[ModuleDependencyEdge, ...]
+    dependency_order: tuple[ModuleKey, ...]
+    shutdown_order: tuple[ModuleKey, ...]
+
+
+class ModuleRegistry:
+    """当前 Application 的不可变 Module 索引和稳定生命周期顺序。"""
+
+    __slots__ = ("_dependency_order", "_descriptors", "_shutdown_order", "_snapshot", "_startup")
+
+    def __init__(
+        self,
+        *,
+        startup: ModuleDescriptor,
+        descriptors: Mapping[ModuleKey, ModuleDescriptor],
+        dependency_order: tuple[ModuleDescriptor, ...],
+    ) -> None:
+        descriptor_copy = dict(descriptors)
+        self._startup = startup
+        self._descriptors: Mapping[ModuleKey, ModuleDescriptor] = MappingProxyType(descriptor_copy)
+        self._dependency_order = dependency_order
+        self._shutdown_order = tuple(reversed(dependency_order))
+        dependency_map: Mapping[ModuleKey, tuple[ModuleKey, ...]] = MappingProxyType(
+            {descriptor.key: descriptor.dependencies for descriptor in dependency_order}
+        )
+        dependency_path_map: Mapping[ModuleKey, tuple[ModuleKey, ...]] = MappingProxyType(
+            {descriptor.key: descriptor.dependency_path for descriptor in dependency_order}
+        )
+        self._snapshot = ModuleGraphSnapshot(
+            startup=startup.key,
+            dependencies=dependency_map,
+            dependency_paths=dependency_path_map,
+            dependency_edges=tuple(
+                edge for descriptor in dependency_order for edge in descriptor.dependency_edges
+            ),
+            dependency_order=tuple(descriptor.key for descriptor in dependency_order),
+            shutdown_order=tuple(descriptor.key for descriptor in self._shutdown_order),
+        )
+
+    @property
+    def startup(self) -> ModuleDescriptor:
+        return self._startup
+
+    @property
+    def descriptors(self) -> Mapping[ModuleKey, ModuleDescriptor]:
+        return self._descriptors
+
+    @property
+    def dependency_order(self) -> tuple[ModuleDescriptor, ...]:
+        return self._dependency_order
+
+    @property
+    def shutdown_order(self) -> tuple[ModuleDescriptor, ...]:
+        return self._shutdown_order
+
+    @property
+    def snapshot(self) -> ModuleGraphSnapshot:
+        return self._snapshot
+
+    def __getitem__(self, key: ModuleKey) -> ModuleDescriptor:
+        try:
+            return self._descriptors[key]
+        except KeyError:
+            raise UnknownModuleError(key) from None
+
+    def __iter__(self) -> Iterator[ModuleKey]:
+        return iter(self._descriptors)
+
+    def __len__(self) -> int:
+        return len(self._descriptors)

python_platform/modularity/selection.py

@@ -0,0 +1,16 @@
+"""显式模块操作消费最终依赖图，不按包名前缀推断业务归属。"""
+
+from .contracts import AppModule, ModuleKey
+from .registry import ModuleRegistry
+
+
+def _dependency_keys(registry: ModuleRegistry, module: type[AppModule]) -> frozenset[ModuleKey]:
+    key = ModuleKey(module.__module__, module.__qualname__)
+    pending = [registry[key].key]
+    selected: set[ModuleKey] = set()
+    while pending:
+        current = pending.pop()
+        if current not in selected:
+            selected.add(current)
+            pending.extend(registry[current].dependencies)
+    return frozenset(selected)