python-ddd-framework 0.3.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

python_ddd_framework/__init__.py

@@ -1,34 +1,31 @@
 from .application import Application, ApplicationBuilder
 from .application_services import (
     ApplicationInvocationCleanupError,
-    ApplicationInvocationContext,
     ApplicationInvocationRejectedError,
     ApplicationService,
     ApplicationServiceCatalog,
     ApplicationServiceContract,
     ApplicationServiceDefinitionError,
-    ApplicationServiceMethod,
     ApplicationServiceMethodError,
     ApplicationServiceRegistration,
     ApplicationServiceValidationError,
     ApplicationServiceValidationIssue,
     CrossTaskInvocationError,
-    DataSeedContributor,
-    DataSeeder,
-    DataSeedError,
     IntegrationService,
-    InterceptionStage,
-    Interceptor,
-    InterceptorRegistration,
-    MethodInvocation,
     NestedConnectionError,
     application_service,
-    disable_validation,
-    enable_validation,
 )
+from .application_services.module import ApplicationServicesModule
+from .application_services.pagination import (
+    PagedAndSortedResultRequestDto,
+    PagedResult,
+    PagedResultRequestDto,
+)
+from .auditing.module import AuditingModule
 from .authorization import (
     AccessTokenAuthenticator,
     AuthorizationDefinitionError,
+    AuthorizationOptions,
     CurrentUser,
     PermissionCatalog,
     PermissionChecker,
@@ -44,6 +41,7 @@ from .authorization import (
     allow_anonymous,
     authorize,
 )
+from .authorization.module import AuthorizationModule
 from .background_execution import (
     BackgroundExecutionMode,
     BackgroundJobOptions,
@@ -51,6 +49,12 @@ from .background_execution import (
     BackgroundTaskSnapshot,
     BackgroundTaskState,
 )
+from .background_execution.declarations import (
+    BackgroundJobs,
+    BackgroundSchedules,
+    BackgroundWorkers,
+)
+from .background_execution.module import BackgroundExecutionModule
 from .background_jobs import (
     BackgroundJobCatalog,
     BackgroundJobContext,
@@ -75,12 +79,13 @@ from .background_workers import (
     BackgroundWorkerRuntimeError,
 )
 from .caching import (
-    CacheCatalog,
-    CacheDefinition,
-    CacheDefinitionError,
     DistributedCache,
+    DistributedCacheEntryOptions,
     DistributedCacheError,
+    DistributedCacheOptions,
+    cache_name,
 )
+from .caching.module import CachingModule
 from .configuration import (
     ConfigurationContribution,
     ConfigurationProvenance,
@@ -101,10 +106,13 @@ from .diagnostics import (
     SourceLocation,
 )
 from .distributed_lock import DistributedLock, DistributedLockError, DistributedLockOptions
-from .domain import AggregateRoot, Entity, OptimisticConcurrencyError, ValueObject
+from .domain import AggregateRoot, DomainService, Entity, OptimisticConcurrencyError, ValueObject
 from .errors import (
     ApplicationRuntimeError,
     ApplicationStartError,
+    BusinessError,
+    BusinessErrorDefinition,
+    BusinessErrorField,
     CatalogNativeGraphMismatchError,
     CompositionResourceError,
     ConfigurationSourceError,
@@ -136,8 +144,11 @@ from .errors import (
 )
 from .events import (
     AggregateEventCollector,
+    EntityChangedEvent,
+    EntityCreatedEvent,
+    EntityDeletedEvent,
+    EntityUpdatedEvent,
     EventContributionError,
-    EventContributor,
     EventCycleError,
     LocalEventBus,
     LocalEventCatalog,
@@ -147,6 +158,19 @@ from .events import (
     PostCommitEventError,
     local_event_handler,
 )
+from .events.module import LocalEventsModule
+from .events.subscription import subscribe_local_event
+from .extensions import (
+    ExtensibleModel,
+    ExtensionCatalog,
+    ExtensionContribution,
+    ExtensionPoints,
+    ExtensionProperties,
+    ExtensionsModule,
+    ExtensionTarget,
+    ModelExtension,
+    ModelExtensions,
+)
 from .hosted_services import (
     ApplicationReadinessSnapshot,
     HostedService,
@@ -161,6 +185,16 @@ from .hosted_services import (
     HostedServiceSnapshot,
     HostedServiceStatus,
 )
+from .hosted_services.declarations import HostedServices
+from .hosted_services.module import HostedServicesModule
+from .invocation.contracts import ApplicationInvocationContext
+from .invocation.contribution import add_interceptor
+from .invocation.entrypoints import call, call_as, invoke, invoke_as
+from .invocation.execution import MethodInvocation
+from .invocation.interceptors import InterceptionStage, Interceptor, InterceptorRegistration
+from .invocation.methods import ServiceMethod
+from .invocation.module import InvocationModule
+from .invocation.policies import ValidationEnabled, disable_validation, enable_validation
 from .lifecycle import (
     ApplicationState,
     ApplicationView,
@@ -174,8 +208,20 @@ from .lifecycle import (
     ShutdownContext,
     ShutdownReason,
 )
+from .messaging import (
+    MessageChannel,
+    MessageChannelDefinition,
+    MessageHandler,
+    MessageOutcome,
+    MessageReceipt,
+    MessageRejectedError,
+    MessageState,
+    MessagingModule,
+    MessagingOptions,
+)
 from .modularity import (
     AppModule,
+    ModuleDeclaration,
     ModuleDependency,
     ModuleDependencyEdge,
     ModuleDescriptor,
@@ -183,7 +229,9 @@ from .modularity import (
     ModuleKey,
     ModuleRef,
     ModuleRegistry,
+    ModuleRequirement,
 )
+from .notifications.module import NotificationsModule
 from .options import (
     BaseOptions,
     Options,
@@ -195,9 +243,17 @@ from .options import (
 from .realtime import (
     RealtimeDeliveryReport,
     RealtimeEnvelope,
+    RealtimeMessage,
     RealtimePublisher,
     RealtimeSnapshot,
 )
+from .seeding import (
+    DataSeedContributor,
+    DataSeeder,
+    DataSeedError,
+    DataSeedingModule,
+    DataSeedRegistration,
+)
 from .services import (
     ConventionalService,
     ConventionCandidate,
@@ -227,8 +283,11 @@ from .settings import (
     SettingManager,
     SettingProvider,
 )
+from .settings.declarations import SettingHandlers
+from .settings.module import SettingsModule
 from .unit_of_work import (
     UnitOfWork,
+    UnitOfWorkCompletionError,
     UnitOfWorkManager,
     UnitOfWorkOptions,
     UnitOfWorkState,
@@ -236,6 +295,7 @@ from .unit_of_work import (
     UnitOfWorkTransactionBehavior,
     unit_of_work,
 )
+from .unit_of_work.module import UnitOfWorkModule
 
 __all__ = (
     "AccessTokenAuthenticator",
@@ -253,16 +313,20 @@ __all__ = (
     "ApplicationServiceCatalog",
     "ApplicationServiceContract",
     "ApplicationServiceDefinitionError",
-    "ApplicationServiceMethod",
     "ApplicationServiceMethodError",
     "ApplicationServiceRegistration",
     "ApplicationServiceValidationError",
     "ApplicationServiceValidationIssue",
+    "ApplicationServicesModule",
     "ApplicationStartError",
     "ApplicationState",
     "ApplicationView",
+    "AuditingModule",
     "AuthorizationDefinitionError",
+    "AuthorizationModule",
+    "AuthorizationOptions",
     "BackgroundExecutionMode",
+    "BackgroundExecutionModule",
     "BackgroundExecutionOptions",
     "BackgroundExecutionProfile",
     "BackgroundJobCatalog",
@@ -276,6 +340,8 @@ __all__ = (
     "BackgroundJobPayloadError",
     "BackgroundJobRetryPolicy",
     "BackgroundJobSchedule",
+    "BackgroundJobs",
+    "BackgroundSchedules",
     "BackgroundSystemCaller",
     "BackgroundTaskOptions",
     "BackgroundTaskSnapshot",
@@ -286,10 +352,12 @@ __all__ = (
     "BackgroundWorkerDefinition",
     "BackgroundWorkerDefinitionError",
     "BackgroundWorkerRuntimeError",
+    "BackgroundWorkers",
     "BaseOptions",
-    "CacheCatalog",
-    "CacheDefinition",
-    "CacheDefinitionError",
+    "BusinessError",
+    "BusinessErrorDefinition",
+    "BusinessErrorField",
+    "CachingModule",
     "CatalogNativeGraphMismatchError",
     "CompositionResourceError",
     "ConfigurationContribution",
@@ -312,21 +380,36 @@ __all__ = (
     "CurrentUser",
     "DataSeedContributor",
     "DataSeedError",
+    "DataSeedRegistration",
     "DataSeeder",
+    "DataSeedingModule",
     "DiagnosticMessage",
     "DiagnosticSnapshot",
     "DistributedCache",
+    "DistributedCacheEntryOptions",
     "DistributedCacheError",
+    "DistributedCacheOptions",
     "DistributedLock",
     "DistributedLockError",
     "DistributedLockOptions",
+    "DomainService",
     "DuplicateModuleIdentityError",
     "DuplicateOptionDefinitionError",
     "Entity",
+    "EntityChangedEvent",
+    "EntityCreatedEvent",
+    "EntityDeletedEvent",
+    "EntityUpdatedEvent",
     "EventContributionError",
-    "EventContributor",
     "EventCycleError",
     "EventStatus",
+    "ExtensibleModel",
+    "ExtensionCatalog",
+    "ExtensionContribution",
+    "ExtensionPoints",
+    "ExtensionProperties",
+    "ExtensionTarget",
+    "ExtensionsModule",
     "FailureRecord",
     "FrameworkError",
     "GraphInvariantError",
@@ -341,6 +424,8 @@ __all__ = (
     "HostedServiceRegistration",
     "HostedServiceSnapshot",
     "HostedServiceStatus",
+    "HostedServices",
+    "HostedServicesModule",
     "InitializeContext",
     "IntegrationService",
     "InterceptionStage",
@@ -351,6 +436,7 @@ __all__ = (
     "InvalidDiagnosticCodeError",
     "InvalidModuleReferenceError",
     "InvalidOptionDefinitionError",
+    "InvocationModule",
     "LifecycleContext",
     "LifecycleInvocationError",
     "LifecyclePhase",
@@ -361,8 +447,21 @@ __all__ = (
     "LocalEventHandlerError",
     "LocalEventPhase",
     "LocalEventSubscription",
+    "LocalEventsModule",
+    "MessageChannel",
+    "MessageChannelDefinition",
+    "MessageHandler",
+    "MessageOutcome",
+    "MessageReceipt",
+    "MessageRejectedError",
+    "MessageState",
+    "MessagingModule",
+    "MessagingOptions",
     "MethodInvocation",
+    "ModelExtension",
+    "ModelExtensions",
     "ModuleCycleError",
+    "ModuleDeclaration",
     "ModuleDependency",
     "ModuleDependencyEdge",
     "ModuleDescriptor",
@@ -371,8 +470,10 @@ __all__ = (
     "ModuleKey",
     "ModuleRef",
     "ModuleRegistry",
+    "ModuleRequirement",
     "ModuleResolutionError",
     "NestedConnectionError",
+    "NotificationsModule",
     "OptimisticConcurrencyError",
     "Options",
     "OptionsContribution",
@@ -380,6 +481,9 @@ __all__ = (
     "OptionsSnapshot",
     "OptionsValidationError",
     "OptionsValidationIssue",
+    "PagedAndSortedResultRequestDto",
+    "PagedResult",
+    "PagedResultRequestDto",
     "PermissionCatalog",
     "PermissionChecker",
     "PermissionCheckerUnavailableError",
@@ -400,6 +504,7 @@ __all__ = (
     "ProviderContributionView",
     "RealtimeDeliveryReport",
     "RealtimeEnvelope",
+    "RealtimeMessage",
     "RealtimePublisher",
     "RealtimeSnapshot",
     "RegistrationConflictError",
@@ -415,14 +520,17 @@ __all__ = (
     "ServiceCatalog",
     "ServiceContributor",
     "ServiceContributorClosedError",
+    "ServiceMethod",
     "ServiceRegistration",
     "SettingCatalog",
     "SettingDefinition",
     "SettingDefinitionContext",
     "SettingDefinitionError",
     "SettingDefinitionProvider",
+    "SettingHandlers",
     "SettingManager",
     "SettingProvider",
+    "SettingsModule",
     "ShutdownContext",
     "ShutdownReason",
     "SingletonDependency",
@@ -430,20 +538,30 @@ __all__ = (
     "TransientDependency",
     "UnauthenticatedError",
     "UnitOfWork",
+    "UnitOfWorkCompletionError",
     "UnitOfWorkManager",
+    "UnitOfWorkModule",
     "UnitOfWorkOptions",
     "UnitOfWorkState",
     "UnitOfWorkStateError",
     "UnitOfWorkTransactionBehavior",
     "UnknownModuleError",
     "UnknownOptionsError",
+    "ValidationEnabled",
     "ValueObject",
+    "add_interceptor",
     "allow_anonymous",
     "application_service",
     "authorize",
+    "cache_name",
+    "call",
+    "call_as",
     "disable_validation",
     "enable_validation",
+    "invoke",
+    "invoke_as",
     "local_event_handler",
     "service",
+    "subscribe_local_event",
     "unit_of_work",
 )

python_ddd_framework/application/builder.py

@@ -9,31 +9,16 @@ from uuid import uuid4
 
 from pydantic import BaseModel
 
-from ..application_services.invocation import _InvocationRuntime
-from ..authorization.catalog import _build_permission_catalog
-from ..background_jobs.catalog import _build_background_job_catalog
-from ..background_workers import BackgroundExecutionOptions
-from ..background_workers.catalog import _build_background_worker_catalog
-from ..background_workers.runtime import _BackgroundCoordinator
-from ..caching.catalog import _build_cache_catalog
 from ..configuration.composition import _ConfigurationComposer
 from ..configuration.contracts import _ConfigurationDefaultContribution
 from ..diagnostics.journal import _DiagnosticJournal
-from ..events.contribution import EventContributionRegistry
-from ..hosted_services import HostedServiceOptions
-from ..hosted_services.catalog import (
-    _build_hosted_service_catalog,
-    _contribute_hosted_service_defaults,
-)
-from ..hosted_services.runtime import _HostedServiceCoordinator
+from ..lifecycle import RuntimeParticipant
 from ..modularity import AppModule, ModuleDescriptor, ModuleRef
 from ..modularity.discovery import _discover_types, _snapshot_scan_packages
 from ..modularity.graph import _ModuleGraphBuilder
-from ..notifications.catalog import _build_notification_catalog
 from ..options.registry import _OptionsRegistry
 from ..services.contribution import ServiceContributionRegistry
 from ..services.runtime import _ServiceRuntimeBuilder
-from ..settings.catalog import _build_setting_catalog, _contribute_setting_handler_defaults
 from .build_spec import _ApplicationBuildSpec
 from .composition import _CompositionLifecycle
 from .runtime import Application
@@ -85,15 +70,6 @@ class ApplicationBuilder:
         scan_packages = _snapshot_scan_packages(registry)
         discoveries = _discover_types(registry, scan_packages)
         claims: dict[type[BaseModel], tuple[str, ModuleDescriptor]] = {}
-        pre_options_registry = _OptionsRegistry(kind="PreOptions", claims=claims)
-        options_registry = _OptionsRegistry(kind="Options", claims=claims)
-        permission_catalog = _build_permission_catalog(registry, discoveries)
-        cache_catalog = _build_cache_catalog(registry)
-        setting_catalog = _build_setting_catalog(registry, discoveries)
-        notification_catalog = _build_notification_catalog(registry)
-        background_worker_catalog = _build_background_worker_catalog(registry)
-        background_job_catalog = _build_background_job_catalog(registry, discoveries)
-        hosted_service_catalog = _build_hosted_service_catalog(registry)
         configuration = _ConfigurationComposer(
             environment=self._environment,
             base_path=self._base_path,
@@ -113,33 +89,25 @@ class ApplicationBuilder:
         root = _ApplicationStateRoot(
             application_id=uuid4(),
             registry=registry,
+            discoveries=discoveries,
             configuration=configuration,
-            pre_options_registry=pre_options_registry,
-            options_registry=options_registry,
+            pre_options_registry=_OptionsRegistry(kind="PreOptions", claims=claims),
+            options_registry=_OptionsRegistry(kind="Options", claims=claims),
             service_registry=ServiceContributionRegistry(),
-            event_registry=EventContributionRegistry(),
-            permission_catalog=permission_catalog,
-            cache_catalog=cache_catalog,
-            setting_catalog=setting_catalog,
-            background_worker_catalog=background_worker_catalog,
-            background_job_catalog=background_job_catalog,
-            hosted_service_catalog=hosted_service_catalog,
             journal=_DiagnosticJournal(),
             completed_stages={descriptor.key: [] for descriptor in registry.dependency_order},
         )
         _CompositionLifecycle(root).run()
-        _contribute_hosted_service_defaults(hosted_service_catalog, root.service_registry)
-        _contribute_setting_handler_defaults(registry, root.service_registry)
-        root.invocation_runtime = _InvocationRuntime(
-            application_id=root.application_id,
-            state_getter=lambda: root.state,
-        )
-        root.background_coordinator = _BackgroundCoordinator(
-            worker_catalog=background_worker_catalog,
-            job_catalog=background_job_catalog,
-            options=root.require_options().get(BackgroundExecutionOptions),
-            invocation_runtime=root.require_invocation_runtime(),
-            build_spec=_ApplicationBuildSpec(
+        application = Application(root)
+        service_runtime = _ServiceRuntimeBuilder(
+            registry,
+            root.service_registry,
+            scan_packages,
+            discoveries,
+            root.configuration,
+            root.require_options(),
+            application,
+            _ApplicationBuildSpec(
                 self._startup_module,
                 self._environment,
                 self._base_path,
@@ -149,41 +117,18 @@ class ApplicationBuilder:
                 dict(self._explicit_overrides),
                 Path.cwd().resolve(),
             ),
-        )
-        root.hosted_service_coordinator = _HostedServiceCoordinator(
-            catalog=hosted_service_catalog,
-            options=root.require_options().get(HostedServiceOptions),
-            state_getter=lambda: root.state,
-        )
-        service_runtime = _ServiceRuntimeBuilder(
-            registry,
-            root.service_registry,
-            root.event_registry,
-            scan_packages,
-            discoveries,
-            root.configuration,
-            root.require_options(),
-            root.require_invocation_runtime(),
-            permission_catalog,
-            cache_catalog,
-            setting_catalog,
-            notification_catalog,
-            background_worker_catalog,
-            background_job_catalog,
-            root.require_background_coordinator(),
-            hosted_service_catalog,
-            root.require_hosted_service_coordinator(),
         ).build()
         root.service_catalog = service_runtime.catalog
-        root.application_service_catalog = service_runtime.application_service_catalog
-        root.event_catalog = service_runtime.event_catalog
         root.container = service_runtime.container
-        root.require_background_coordinator().attach_container(service_runtime.container)
-        root.require_hosted_service_coordinator().attach_container(
-            service_runtime.container,
-            service_runtime.application_service_catalog,
-        )
-        return Application(root)
+        participants: list[RuntimeParticipant] = []
+        for descriptor in registry.dependency_order:
+            participant = descriptor.instance.runtime
+            if participant is not None:
+                if not isinstance(participant, RuntimeParticipant):
+                    raise TypeError(f"{descriptor.key}.runtime must be RuntimeParticipant or None")
+                participants.append(participant)
+        root.runtimes = tuple(participants)
+        return application
 
 
 def _validate_environment(environment: str) -> str:

python_ddd_framework/application/composition.py

@@ -6,18 +6,13 @@ import inspect
 from collections.abc import Callable
 from typing import cast
 
-from ..auditing import AuditingOptions
-from ..background_workers import BackgroundExecutionOptions
 from ..diagnostics import EventStatus, LifecyclePhase, LifecycleStage
 from ..errors import (
     CompositionResourceError,
     LifecycleInvocationError,
 )
-from ..hosted_services import HostedServiceOptions
-from ..hosted_services.options import HOSTED_SERVICE_OPTIONS_SECTION
 from ..lifecycle import ConfigureContext, PostConfigureContext, PreConfigureContext
 from ..modularity import ModuleDescriptor
-from ..unit_of_work import UnitOfWorkOptions
 from .state import (
     LIFECYCLE_ERROR_TYPE,
     _ApplicationStateRoot,
@@ -45,19 +40,9 @@ class _CompositionLifecycle:
         for descriptor in self._root.registry.dependency_order:
             self._invoke_post_configure(descriptor)
         options = self._root.options_registry
-        owner = self._root.registry.startup
-        # 常驻框架能力的默认声明只有此处负责；显式 Module 声明优先，默认值仍由 model 验证。
-        options.declare_default(BackgroundExecutionOptions, "background_execution", owner=owner)
-        options.declare_default(HostedServiceOptions, HOSTED_SERVICE_OPTIONS_SECTION, owner=owner)
-        options.declare_default(AuditingOptions, "auditing", owner=owner)
-        options.declare_default(UnitOfWorkOptions, "unit_of_work", owner=owner)
         self._root.options = options.bind_options(self._root.configuration)
         self._root.configuration = self._root.configuration._finalize(
-            sections=(
-                options.sections
-                | self._root.pre_options_registry.sections
-                | ({"settings"} if self._root.setting_catalog.definitions else set())
-            ),
+            sections=(options.sections | self._root.pre_options_registry.sections),
             secret_paths=options.secret_paths | self._root.pre_options_registry.secret_paths,
             mapping_paths=lambda values, reference: (
                 options.mapping_paths(values, reference, self._root.options)
@@ -101,11 +86,9 @@ class _CompositionLifecycle:
             descriptor=descriptor,
             stage=stage,
         )
-        events = self._root.event_registry.contributor(
-            descriptor=descriptor,
-            stage=stage,
-        )
         context = ConfigureContext(
+            modules=self._root.registry,
+            discoveries=self._root.discoveries,
             application_id=self._root.application_id,
             descriptor=descriptor,
             stage=stage,
@@ -115,7 +98,6 @@ class _CompositionLifecycle:
             pre_options=self._root.require_pre_options(),
             configure=editor,
             services=services,
-            events=events,
         )
         callback = cast(
             Callable[[ConfigureContext], object],
@@ -126,7 +108,6 @@ class _CompositionLifecycle:
         finally:
             editor._close()
             services._close()
-            events._close()
 
     def _invoke_post_configure(self, descriptor: ModuleDescriptor) -> None:
         stage = LifecycleStage.POST_CONFIGURE
@@ -139,6 +120,7 @@ class _CompositionLifecycle:
             stage=stage,
         )
         context = PostConfigureContext(
+            modules=self._root.registry,
             application_id=self._root.application_id,
             descriptor=descriptor,
             stage=stage,