python-ddd-framework 0.9.0__py3-none-any.whl → 0.10.1__py3-none-any.whl

python_ddd_framework/__init__.py

@@ -106,7 +106,16 @@ from .diagnostics import (
     SourceLocation,
 )
 from .distributed_lock import DistributedLock, DistributedLockError, DistributedLockOptions
-from .domain import AggregateRoot, DomainService, Entity, OptimisticConcurrencyError, ValueObject
+from .domain import (
+    AggregateRoot,
+    DomainService,
+    Entity,
+    GeneratesLocalEvents,
+    HasVersion,
+    OptimisticConcurrencyError,
+    ValueObject,
+)
+from .entity_caching import EntityCache, EntityCachingModule, add_entity_cache
 from .errors import (
     ApplicationRuntimeError,
     ApplicationStartError,
@@ -263,6 +272,7 @@ from .services import (
     ProviderContributionView,
     RegistrationDecision,
     RegistrationKind,
+    Repository,
     RepositoryContract,
     ScopedDependency,
     ServiceCatalog,
@@ -396,6 +406,8 @@ __all__ = (
     "DuplicateModuleIdentityError",
     "DuplicateOptionDefinitionError",
     "Entity",
+    "EntityCache",
+    "EntityCachingModule",
     "EntityChangedEvent",
     "EntityCreatedEvent",
     "EntityDeletedEvent",
@@ -412,7 +424,9 @@ __all__ = (
     "ExtensionsModule",
     "FailureRecord",
     "FrameworkError",
+    "GeneratesLocalEvents",
     "GraphInvariantError",
+    "HasVersion",
     "HostedService",
     "HostedServiceCatalog",
     "HostedServiceContext",
@@ -510,6 +524,7 @@ __all__ = (
     "RegistrationConflictError",
     "RegistrationDecision",
     "RegistrationKind",
+    "Repository",
     "RepositoryContract",
     "ResourceConflictError",
     "ResourceNotFoundError",
@@ -549,6 +564,7 @@ __all__ = (
     "UnknownOptionsError",
     "ValidationEnabled",
     "ValueObject",
+    "add_entity_cache",
     "add_interceptor",
     "allow_anonymous",
     "application_service",

python_ddd_framework/application/builder.py

@@ -97,38 +97,44 @@ class ApplicationBuilder:
             journal=_DiagnosticJournal(),
             completed_stages={descriptor.key: [] for descriptor in registry.dependency_order},
         )
-        _CompositionLifecycle(root).run()
-        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,
-                self._env_prefix,
-                self._cli_args,
-                self._dotenv_path,
-                dict(self._explicit_overrides),
-                Path.cwd().resolve(),
-            ),
-        ).build()
-        root.service_catalog = service_runtime.catalog
-        root.container = service_runtime.container
-        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
+        # 组装中的原生资源可能早于容器创建；失败回滚和成功后的运行时清理共用一个 owner。
+        with root.composition_resources:
+            _CompositionLifecycle(root).run()
+            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,
+                    self._env_prefix,
+                    self._cli_args,
+                    self._dotenv_path,
+                    dict(self._explicit_overrides),
+                    Path.cwd().resolve(),
+                ),
+                root.composition_resources,
+            ).build()
+            root.service_catalog = service_runtime.catalog
+            root.container = service_runtime.container
+            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)
+            root.composition_resources = root.composition_resources.pop_all()
+            return application
 
 
 def _validate_environment(environment: str) -> str:

python_ddd_framework/application/runtime_hooks.py

@@ -83,11 +83,9 @@ class _RuntimeLifecycle:
         exception: BaseException | None,
     ) -> tuple[ContainerCleanupError, ...]:
         container = self._root.container
-        if container is None:
-            return ()
         failures: list[ContainerCleanupError] = []
         try:
-            while True:
+            while container is not None:
                 try:
                     await container.close(exception)
                 except BaseException as original_error:
@@ -99,6 +97,10 @@ class _RuntimeLifecycle:
         finally:
             # 只在 native close 已穷尽后撤销引用；stop 后不再暴露可解析容器。
             self._root.container = None
+            try:
+                self._root.composition_resources.close()
+            except BaseException as original_error:
+                failures.append(self._container_cleanup_error(original_error))
         return tuple(failures)
 
     def _container_cleanup_error(

python_ddd_framework/application/state.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import asyncio
 from collections.abc import Callable
+from contextlib import ExitStack
 from dataclasses import dataclass, field
 from typing import assert_never
 from uuid import UUID
@@ -41,6 +42,7 @@ class _ApplicationStateRoot:
     options: OptionsSnapshot | None = None
     service_catalog: ServiceCatalog | None = None
     container: AsyncContainer | None = None
+    composition_resources: ExitStack = field(default_factory=ExitStack)
     state: ApplicationState = ApplicationState.COMPOSED
     transition_token: object | None = None
     runtime_touched: set[ModuleKey] = field(default_factory=set)

python_ddd_framework/auditing/sqlalchemy/mappings.py

@@ -0,0 +1,29 @@
+"""审计记录使用原生表；事件记录到日志字段的业务投影归 AuditSink。"""
+
+from sqlalchemy import BigInteger, Boolean, Column, DateTime, Integer, MetaData, String, Table
+from sqlalchemy.orm import registry
+
+from ...sqlalchemy import NativeUuid, sqlalchemy_mapping
+
+AUDIT_TABLE = "audit_logs"
+
+
+@sqlalchemy_mapping
+def configure_auditing(mapper_registry: registry, metadata: MetaData) -> None:
+    Table(
+        AUDIT_TABLE,
+        metadata,
+        Column("audit_id", NativeUuid(), primary_key=True),
+        Column("occurred_at", DateTime(timezone=True), nullable=False),
+        Column("kind", String(32), nullable=False, index=True),
+        Column("user_id", NativeUuid(), nullable=True, index=True),
+        Column("session_id", NativeUuid(), nullable=True),
+        Column("correlation_id", String(128), nullable=False, index=True),
+        Column("route_template", String(512), nullable=True),
+        Column("contract", String(512), nullable=True),
+        Column("method", String(128), nullable=True),
+        Column("status_code", Integer, nullable=True),
+        Column("succeeded", Boolean, nullable=True),
+        Column("duration_ns", BigInteger, nullable=False),
+        Column("exception_type", String(256), nullable=True),
+    )

python_ddd_framework/auditing/sqlalchemy/module.py

@@ -12,13 +12,12 @@ from ...sqlalchemy import (
     contributes_sqlalchemy_models,
 )
 from ..contracts import AuditSink
-from .models import AuditingBase
 from .store import SqlAlchemyAuditSink
 
 
 @contributes_sqlalchemy_models(
     SqlAlchemyModelRegistration(
-        metadata=AuditingBase.metadata,
+        mappings_package=__package__ + ".mappings",
         migrations_package="python_ddd_framework.auditing.sqlalchemy.migrations",
         branch_label="auditing",
     )

python_ddd_framework/auditing/sqlalchemy/store.py

@@ -4,21 +4,29 @@ from __future__ import annotations
 
 from uuid import uuid4
 
-from ...sqlalchemy.auditing import FrameworkAsyncSession
-from ...sqlalchemy.runtime import _SqlAlchemyEngineRegistry
+from sqlalchemy import insert
+
+from ...sqlalchemy import SqlAlchemyModelCatalog, SqlAlchemySessionProvider
+from ...unit_of_work import UnitOfWorkManager
 from ..contracts import ApplicationServiceAuditRecord, RequestAuditRecord
-from .models import AuditLogRow
+from . import mappings
 
 
 class SqlAlchemyAuditSink:
-    __slots__ = ("_engines",)
+    __slots__ = ("_manager", "_provider", "_table")
 
-    def __init__(self, engines: _SqlAlchemyEngineRegistry) -> None:
-        self._engines = engines
+    def __init__(
+        self,
+        manager: UnitOfWorkManager,
+        provider: SqlAlchemySessionProvider,
+        catalog: SqlAlchemyModelCatalog,
+    ) -> None:
+        self._manager, self._provider = manager, provider
+        self._table = catalog.metadata_for(mappings.__name__).tables[mappings.AUDIT_TABLE]
 
     async def write_request(self, record: RequestAuditRecord) -> None:
         await self._write(
-            AuditLogRow(
+            dict(
                 audit_id=uuid4(),
                 occurred_at=record.occurred_at,
                 kind="request",
@@ -37,7 +45,7 @@ class SqlAlchemyAuditSink:
 
     async def write_application_service(self, record: ApplicationServiceAuditRecord) -> None:
         await self._write(
-            AuditLogRow(
+            dict(
                 audit_id=uuid4(),
                 occurred_at=record.occurred_at,
                 kind="application_service",
@@ -54,10 +62,10 @@ class SqlAlchemyAuditSink:
             )
         )
 
-    async def _write(self, row: AuditLogRow) -> None:
-        async with FrameworkAsyncSession(
-            self._engines.get("default"),
-            expire_on_commit=False,
-        ) as session:
-            async with session.begin():
-                session.add(row)
+    async def _write(self, values: dict[str, object]) -> None:
+        async with self._manager.begin(
+            requires_new=True, connection_name="default", is_transactional=True
+        ) as work:
+            session = await self._provider.get_session()
+            await session.execute(insert(self._table).values(**values))
+            await work.complete()

python_ddd_framework/caching/unit_of_work.py

@@ -18,6 +18,10 @@ class _CachePending:
     async def before_commit(self) -> None:
         pass
 
+    @property
+    def has_pending(self) -> bool:
+        return False
+
     async def after_commit(self) -> None:
         failures: list[Exception] = []
         try:

python_ddd_framework/consumer_docs/README.md

@@ -0,0 +1,91 @@
+# Framework consumer guide
+
+These resources belong to the installed `python-ddd-framework` distribution. Use the Python package `python_ddd_framework` in the application's own backend environment; the repository checkout, global CLI, and generated-template version are not substitutes for that artifact. The application's `docs/development.md#framework-documentation` owns environment lookup and setup failures.
+
+Read the capability index, then the relevant **contract and usage** together. Installing dependencies, composing Modules, starting resources, and readiness are separate facts. Examples describe framework use; they do not authorize application business rules, dependencies, tests, or infrastructure changes.
+
+<a id="capabilities"></a>
+
+## Capabilities
+
+Each row identifies supported behavior, its public owner, both reading destinations, and an executable reference in the [same-version Demo](#demo). Demo paths are relative to its backend; bare test names and business/ paths are under tests/integration. The links to installed source are evidence for the entry points, not instructions to modify the installation. This is a navigation index, not a runtime module registry; declarations and metadata still own activation.
+
+| Task / capability | Public entry or owner | Contract | Usage and activation | Demo source / activation / verification |
+| --- | --- | --- | --- | --- |
+| Compose an application; start and stop resources | [ApplicationBuilder](../application/__init__.py), [AppModule and declarations](../modularity/__init__.py) | [Ownership and lifecycle](architecture.md#configuration-and-lifecycle) | [Modules and lifecycle](development.md#modules-and-lifecycle) | `src/host/module.py`; start Web or Worker; `tests/integration/test_reference_app.py` |
+| Bind configuration; configure composition before startup | [Configuration](../configuration/__init__.py), [Options and PreOptions](../options/__init__.py) | [Configuration](architecture.md#configuration-and-lifecycle) | [Options](development.md#options-and-settings) | `src/modules/orders/application/options`; local YAML and CLI overrides; `business/test_http_capabilities.py` |
+| Register, inject, replace, or multi-bind ordinary services | [Services](../services/__init__.py), native Dishka | [Scopes and calls](architecture.md#calls-scopes-and-transactions) | [DI and replacement](development.md#dependency-injection) | `src/modules/orders/application/services`; Module scan and native DI; `business/test_background_business_di.py` |
+| Implement a use case, page results, or call an internal service | [Application services](../application_services/__init__.py), [invocation](../invocation/entrypoints.py) | [Contracts and call boundaries](architecture.md#business-module-boundaries) | [Services and permissions](development.md#services-and-permissions) | `src/modules/orders/application/services`; authenticated order requests; `business/test_business_ddd.py` |
+| Validate inputs; expose safe business errors | [Validation](../validation/__init__.py), [errors](../errors/__init__.py) | [Validation and errors](architecture.md#validation-and-errors) | [Validation and errors](development.md#validation-and-errors) | `src/modules/orders/domain/value_objects`; invalid order inputs; `business/test_boundary_business.py` |
+| Model aggregates and values; persist and query them | [Domain](../domain/__init__.py), [SQLAlchemy](../sqlalchemy/__init__.py) | [Domain and persistence](architecture.md#calls-scopes-and-transactions) | [Repositories, mappings and migrations](development.md#persistence-and-migrations) | `src/modules/orders/sqlalchemy`; explicit migrate and Seed; `business/test_business_ddd.py` |
+| Define transaction boundaries and post-commit work | [UnitOfWorkManager](../unit_of_work/__init__.py) | [Unit of work](architecture.md#unit-of-work) | [Unit of work](development.md#unit-of-work) | `src/modules/orders/application/services`; managed service calls; `business/test_domain_services_events.py` |
+| Handle local domain changes; contribute seed data | [Events](../events/__init__.py), [seeding](../seeding/__init__.py) | [Event values and transactions](architecture.md#calls-scopes-and-transactions) | [Events](development.md#events-and-background-work), [seed procedure](development.md#persistence-and-migrations) | `src/modules/orders/application/event_handlers`; committed changes; `business/test_domain_services_events.py` |
+| Authenticate; manage users, roles, permissions and sessions | [Identity](../identity/__init__.py), [authorization](../authorization/__init__.py) | [Identity and authorization](architecture.md#identity-and-authorization) | [Identity](development.md#identity-management), [service authorization](development.md#services-and-permissions) | `src/modules/customer`; migrate Identity and extension, then log in; `test_enterprise_e2e.py` |
+| Expose HTTP, filters, uploads and downloads | [FastAPI integration](../fastapi/__init__.py) | [HTTP boundaries](architecture.md#http-and-files) | [HTTP and files](development.md#http-files-and-real-time-communication) | `src/modules/orders/http_api`; authenticated HTTP; `business/test_http_pipeline.py` |
+| Stream HTTP output with continuing access checks | [HttpRouter and native FastAPI](../fastapi/__init__.py) | [Streaming](architecture.md#http-streaming-and-continuous-access) | [Complete generator example](development.md#http-generators-and-continuous-access) | `src/modules/orders/http_api/routers`; stream routes; `test_http_streaming.py` |
+| Deliver typed online WebSocket messages | [Realtime](../realtime/__init__.py), [FastAPI realtime](../fastapi/realtime/__init__.py) | [Online delivery](architecture.md#background-work-and-external-boundaries) | [Realtime](development.md#realtime-and-notifications) | `src/modules/orders/http_api/websockets`; connect authenticated socket; `business/test_http_capabilities.py` |
+| Publish typed notifications | [Notifications](../notifications/__init__.py) | [Notification delivery](architecture.md#notifications) | [Notifications](development.md#realtime-and-notifications) | `src/host/module.py` selects RedisNotificationsModule; `test_notifications.py` |
+| Extend DTOs and supported entities; own extension migrations | [Extensions](../extensions/__init__.py), [SQLAlchemy extensions](../sqlalchemy/__init__.py) | [Extension ownership](architecture.md#extension-ownership) | [Extension recipe](development.md#extend-reusable-modules) | `src/modules/customer`; extension migration after Identity; `test_model_extensions.py` |
+| Cache typed values and defer writes until commit | [DistributedCache](../caching/__init__.py) | [Cache and transaction limits](architecture.md#calls-scopes-and-transactions) | [Caching](development.md#events-and-background-work) | `src/modules/orders/application/caching/statistics_cache.py` and `background_jobs/order_statistics/handler.py`; `tests/integration/test_slice3_data_e2e.py` |
+| Cache read-only entities with repository fallback and CRUD invalidation | [EntityCache and registration](../entity_caching/__init__.py) | [Entity caching](architecture.md#entity-caching) | [Registration and queries](development.md#entity-caching) | `src/modules/orders/application/module.py` and `services/order_query_service.py`; `tests/integration/test_entity_caching.py` |
+| Read and conditionally change global runtime settings | [Settings](../settings/__init__.py) | [Settings ownership](architecture.md#global-settings-ownership) | [Definitions, reads and writes](development.md#global-settings) | `src/modules/orders/domain/settings`; change approval setting with its version; `business/test_boundary_business.py` |
+| Run durable jobs, schedules and periodic workers; manage execution | [Background execution](../background_execution/__init__.py), [jobs](../background_jobs/__init__.py), [workers](../background_workers/__init__.py) | [Execution boundaries](architecture.md#background-work-and-external-boundaries) | [Background execution](development.md#events-and-background-work) | `src/modules/orders/application/background_jobs` and `background_workers`; execution profile/modes; `business/test_recovery_capabilities.py` |
+| Own an SDK, thread or long-lived resource | [Hosted services](../hosted_services/__init__.py) | [Shutdown and ownership](architecture.md#background-work-and-external-boundaries) | [Hosted services](development.md#hosted-services) | `src/modules/orders/application/hosted_services`; declared HostedServices; `business/test_background_business_di.py` |
+| Transfer bounded in-process messages and preserve accepted work | [Messaging](../messaging/__init__.py) | [Message lifecycle](architecture.md#configuration-and-lifecycle) | [Channels and handlers](development.md#in-process-messages) | `src/modules/orders/application/hosted_services/observation_module.py`; explicitly add ObservationModule to Host dependencies; `test_reference_app.py` |
+| Acquire a business lease across processes | [DistributedLock](../distributed_lock/__init__.py), [Redis provider](../redis/__init__.py) | [Lease limits](architecture.md#distributed-locks) | [Acquisition and cleanup](development.md#distributed-locks) | `src/modules/orders/application/background_workers/order_maintenance_worker.py`; selected Redis provider; `test_distributed_lock.py` |
+| Audit operations and entities | [Auditing](../auditing/__init__.py) | [Auditing](architecture.md#auditing-and-observability) | [Auditing](development.md#auditing-and-observability) | `src/host/module.py` selects auditing; managed mutations; `test_enterprise_e2e.py` |
+| Inspect composition; configure structured logs and tracing | [Diagnostics](../diagnostics/__init__.py), [observability](../observability/__init__.py) | [Observation boundaries](architecture.md#auditing-and-observability) | [Inspection](development.md#inspect-configuration), [logging and tracing](development.md#auditing-and-observability) | `src/host/module.py` selects logging/tracing; enable export in local configuration when needed; `test_observability.py` |
+| Test an application using its real builder and typed contracts | [TestApplication](../testing/__init__.py) | [Testing boundary](architecture.md#testing) | [Test lifecycle](development.md#testing), [verification](development.md#verification) | `tests/integration/business/test_domain_services_events.py`; real builder plus FrameworkTestApplication |
+| Generate an application/module; operate and deploy a Host | [CLI](../cli/__init__.py), [server](../fastapi/server.py) | [Delivery ownership](architecture.md#documentation-ownership) | [CLI](development.md#cli-operations), [database setup](development.md#initialize-the-database), [deployment](development.md#deployment) | `src/host/main.py`, `worker.py`, `migrate.py`; Demo setup; repository `tests/cli_delivery` |
+
+Choose a capability from the confirmed business need, not from a directory name. Read [implementation workflow](development.md#implementation-workflow) before writing code, and [ownership](architecture.md#ownership-and-dependencies) before changing boundaries. If a capability appears missing, check the relevant installed public API and formal extension point, identify the exact missing behavior, and report it before proposing new infrastructure. Reading every implementation file is not required.
+
+<a id="migration-notes"></a>
+
+## Upgrade reference
+
+The framework's root README owns the current installation and upgrade procedure. That exact README is carried in this distribution's metadata; there is no separately maintained copy here. In the application's backend environment, use the same project interpreter as document lookup with `-I -B -c` and the following Python code:
+
+```python
+from email.parser import Parser
+from importlib.metadata import distribution
+
+installed = distribution("python-ddd-framework")
+metadata_text = installed.read_text("METADATA")
+if metadata_text is None:
+    raise RuntimeError("The installed framework has no METADATA resource")
+print(Parser().parsestr(metadata_text).get_payload())
+```
+
+Before an upgrade, read the target release's README and capability guides from its actual release artifact or versioned release reference. The installed metadata describes the installed version, not a future target. Check required capabilities, enablement conditions, public contracts and application-specific data migration needs. Upgrades change dependencies and package resources, not application Markdown or business code. Follow the application's upgrade procedure and deliberately adapt affected project documentation. A guidance or source lookup is never permission to upgrade, regenerate, migrate data, or edit installed files.
+
+<a id="demo"></a>
+
+## Obtain the same-version Demo
+
+The framework sdist includes `examples/framework_demo`, a complete MIT application with Web and Worker entry points, sample configuration, module-owned migrations and Seed, and the integration suite. It is not included in the runtime wheel and does not require the private repository. Its README contains independent setup and startup instructions; pytest is not needed to run the application. Internal algorithm/failure branches remain covered by framework unit tests rather than invented business endpoints.
+
+In your application's environment, run this standard-library code with the same interpreter used for installed documentation lookup. It resolves the **installed version's** public PyPI sdist, verifies the index SHA-256, and saves it without overwriting an existing file:
+
+```python
+import hashlib
+import json
+from importlib.metadata import version
+from pathlib import Path
+from urllib.request import urlopen
+
+installed = version("python-ddd-framework")
+with urlopen(f"https://pypi.org/pypi/python-ddd-framework/{installed}/json", timeout=30) as response:
+    release = json.load(response)
+source, = (file for file in release["urls"] if file["packagetype"] == "sdist")
+with urlopen(source["url"], timeout=60) as response:
+    content = response.read()
+if hashlib.sha256(content).hexdigest() != source["digests"]["sha256"]:
+    raise RuntimeError("The sdist hash does not match PyPI")
+destination = Path(source["filename"]).name
+with open(destination, "xb") as output:
+    output.write(content)
+print(destination)
+```
+
+Extract the archive into a new directory and open its `examples/framework_demo/README.md`. If that exact version is not published or has no sdist, stop and obtain the matching validated distribution from its owner; do not silently substitute main, a private checkout or another version. Downloading does not authorize infrastructure changes. The Demo pins the same framework version and ships configuration examples only; provide local connections and secrets before migration, Seed or startup. Framework self-authored code is MIT; third-party notices remain attached to their owners. Templates do not select a license for your application's own business code.