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

python_ddd_framework/__init__.py

@@ -284,7 +284,6 @@ from .settings import (
     SettingManager,
     SettingProvider,
 )
-from .settings.declarations import SettingHandlers
 from .settings.module import SettingsModule
 from .unit_of_work import (
     UnitOfWork,
@@ -528,7 +527,6 @@ __all__ = (
     "SettingDefinitionContext",
     "SettingDefinitionError",
     "SettingDefinitionProvider",
-    "SettingHandlers",
     "SettingManagementAccess",
     "SettingManager",
     "SettingProvider",

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/README.md

@@ -32,6 +32,12 @@ All responsibility directories and package markers are retained for navigation.
 5. Conventional HTTP exposure can discover the new public service contracts. Add manual routers only where the transport requires them; keep use-case rules out of HTTP. Register workers, jobs, hosted services, schedules, or event handlers explicitly when required.
 6. Update this responsibility record and run the smallest relevant existing checks. New tests and infrastructure validation require the task's authorization; neither an empty test directory nor successful composition proves business correctness.
 
+## Global settings
+
+When a use case requires a global setting, place its `SettingDefinition` and synchronous definition provider under `domain/settings`, add SettingsModule to the Domain Module dependencies, and include the package in discovery. Callers import the same definition and inject SettingProvider; authorized writes use SettingManager with the version read by the caller. Provider selection and database setup belong to the Host.
+
+Follow the application's [Global settings recipe](../../../../docs/development.md#global-settings) for configuration fallback, management permissions, and update/reset requests. Record this module's actual setting names, business use, and effective timing here when implemented. The skeleton has no business settings or observers; reset clears an override, and the framework does not apply values to running components.
+
 ## Persistence and verification
 
 An empty skeleton retains model and migration registration but has no business tables or revisions. Migration commands still use the configured database; an empty registered Base is different from a module with no model registration. Add actual models before generating a business revision, and review it before applying:

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/AGENTS.md

@@ -23,6 +23,7 @@ Use the [official CLI entry points](docs/development.md#cli-operations) for oper
 ## Preserve ownership and contracts
 
 - The Host composes modules, selects providers, and supplies configuration. Keep business state and rules in their owning modules.
+- Global Settings definitions belong to their Domain Module; services own when values are read and applied. Follow the project's [Settings contract](docs/architecture.md#global-settings-ownership) and [usage recipe](docs/development.md#global-settings), preserving source, authorization, and version rules. Do not assume a component-refresh or notification service exists.
 - Domain and application contracts stay independent of Host, HTTP, and persistence implementations. Cross-module calls use explicitly declared dependencies and public contracts; do not access another module's implementation, ORM models, or tables directly.
 - Use framework application services, repositories, Options, permissions, units of work, events, jobs, and lifecycle hooks before adding custom infrastructure. Do not introduce a parallel DI container, service locator, transaction manager, or wrapper without a missing business capability.
 - Keep public contracts, mutable state, orchestration, and external I/O under clear owners. Split for independent responsibilities, not a fixed line count. Avoid generic `common`, `utils`, or `helpers` collections and speculative abstractions.

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/README.md

@@ -87,6 +87,12 @@ pddd inspect --environment development
 
 Inspection composes and closes a new Application without starting it. It does not query an existing process, and its input snapshot is not the final Options view. Configuration, workers, jobs, real-time communication, and logging are covered in the [development guide](docs/development.md).
 
+## Use global settings
+
+The Host includes Settings persistence and management HTTP. After database setup, define each required setting in its owning module and grant management read/write permissions to the intended identity. Follow the self-contained [Global settings recipe](docs/development.md#global-settings) for definition discovery, YAML/environment fallback, service injection, and HTTP read/update/reset.
+
+Settings stores global values; business code decides when they take effect. Reset clears a runtime override and resumes configuration/default fallback. Source restrictions, visibility, authorization, and version checks remain enforced. No business settings or automatic component-refresh workflow are generated.
+
 ## Test and package
 
 ```sh

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/backend/src/host/module.py.jinja

@@ -21,8 +21,6 @@ from python_ddd_framework.observability.logging import StructuredLoggingModule
 from python_ddd_framework.observability.tracing import TracingModule
 from python_ddd_framework.redis import RedisDistributedLockModule, RedisModule
 from python_ddd_framework.redis.notifications import RedisNotificationsModule
-from python_ddd_framework.settings.notifications import SettingsNotificationsModule
-from python_ddd_framework.settings.refresh_module import SettingsRefreshModule
 from python_ddd_framework.settings.sqlalchemy import SqlAlchemyRuntimeSettingsModule
 
 
@@ -36,8 +34,6 @@ class {{ cookiecutter.class_prefix }}HostModule(AppModule):
         RedisModule,
         RedisDistributedLockModule,
         RedisNotificationsModule,
-        SettingsNotificationsModule,
-        SettingsRefreshModule,
         PgQueuerBackgroundJobsModule,
         BackgroundManagementHttpApiModule,
         StructuredLoggingModule,

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/architecture.md

@@ -83,6 +83,12 @@ These constraints apply when a capability models aggregates. The module README o
 | Cross-aggregate consistency | Before implementing a write spanning aggregates, identify the participating owners, what commits atomically, and any later effects. Record concurrency, failure-after-commit, duplicate/retry, and idempotency behavior. A local UoW may coordinate multiple aggregates when that is the confirmed requirement; do not impose one aggregate per transaction mechanically. Cross-module collaboration still uses public contracts, and local events do not promise durable distributed delivery. |
 | Business evidence | For each changed invariant, the module README must identify its rule owner, business operation, and a concrete rejection example, linking the relevant source and verification. Record unverified cases and open decisions explicitly. Directory placement, type checks, and passing unrelated tests do not by themselves prove a business rule. |
 
+## Global settings ownership
+
+Settings owns global definitions, reads, conditional writes, and clearing overrides. Domain Modules contribute definitions under `domain/settings`; the Host selects persistence and management HTTP. Business services decide when to read and apply values. Source precedence is runtime override, Host configuration, then definition default, filtered by the definition's allowed sources.
+
+Management visibility and permissions govern the generic management service. Internal business services own their authorization; all writes still enforce definition ownership, value validation, and version checks. Settings commits independently of an outer business UoW, and reset retains a fresh version record. It does not own component refresh, notifications, reconciliation, retries, or application status. Follow the [usage recipe](development.md#global-settings) for concrete declarations and calls.
+
 ## Calls, scopes, and transactions
 
 A managed service call passes through authorization, validation, ACTION scope, unit-of-work handling, and the final implementation. HTTP and direct service invocation share this pipeline. Inject the public service contract; do not construct implementations to bypass it. A self-call is an ordinary Python call and does not re-enter the pipeline.

python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/development.md

@@ -128,7 +128,7 @@ For `basic`, keep public interfaces in `contracts/` and implementations in `serv
 | `domain_shared` | `constants`, `enums`, `errors`, `permissions`, `messages`, `value_objects` |
 | `domain` | `entities`, `value_objects`, `services`, `repositories`, `events`, `settings`, `seeding` |
 | `application_contracts` | `services`, `integration_services`, `inputs`, `views` |
-| `application` | `services`, `integration_services`, `background_jobs`, `background_workers`, `hosted_services`, `event_handlers`, `interceptors`, `caching`, `options`, `setting_handlers` |
+| `application` | `services`, `integration_services`, `background_jobs`, `background_workers`, `hosted_services`, `event_handlers`, `interceptors`, `caching`, `options` |
 | `sqlalchemy` | `models`, `repositories`, `migrations` |
 | `http_api` | `routers`, `filters`, `websockets`, `models` |
 
@@ -238,7 +238,67 @@ orders:
 
 The corresponding environment key is `PDDD_ORDERS__ALLOW_BACKGROUND_APPROVAL`. `PDDD_HTTP__API_PREFIX` changes the business API prefix. `{{ cookiecutter.host_environment_variable }}` selects the Host environment and is separate from business configuration. Values that affect composition require the framework's pre-configuration phase; do not read unbound Options during construction.
 
-Use runtime settings when a value must be changed while the application is running. Add definitions through a scanned `SettingDefinitionProvider`, read them through `SettingProvider`, and use `SettingManager` or the management API for conditional updates/reset with the queried version token. Application services can use `self.setting_provider` during managed invocation, not during construction. Setting definitions belong under `domain/settings/`; declare SettingsModule on the owner when introducing them.
+### Global settings
+
+Settings defines, reads, writes, and clears global runtime overrides. The following is an illustrative recipe, not a generated business feature. Add a definition and its provider under the owning module's `domain/settings/worker_settings.py` only when the setting is required:
+
+```python
+from python_ddd_framework.settings import (
+    SettingDefinition,
+    SettingDefinitionContext,
+    SettingDefinitionProvider,
+)
+
+WORKER_LIMIT = SettingDefinition("worker.limit", int, default=10)
+
+
+class WorkerSettingDefinitionProvider(SettingDefinitionProvider):
+    def define(self, context: SettingDefinitionContext) -> None:
+        context.add(WORKER_LIMIT)
+```
+
+Add `SettingsModule` from `python_ddd_framework` to the existing Domain Module's dependencies, and include its package in `scan_packages`; retain the other dependencies and lifecycle hooks. Import this same definition in callers instead of constructing another object with the same name. Store credentials in Host configuration, not Settings.
+
+By default, values resolve from runtime override, Host configuration, then definition default. An optional Host value in `backend/app.development.yaml` looks like this:
+
+```yaml
+settings:
+  worker:
+    limit: 12
+```
+
+The default environment key is `PDDD_SETTINGS__WORKER__LIMIT`. Without an override the value is 12, or 10 if that configuration is absent. Writing 20 makes it the override; reset resumes the configured 12. Configuration is frozen at startup: restart the Host after changing YAML/environment inputs. Reset does not reload files, and writing the default value still creates an override.
+
+Inject `SettingProvider` for reads and `SettingManager` into an authorized service for writes. In an existing async service method, with `reader` and `manager` already injected:
+
+```python
+limit = await reader.get(WORKER_LIMIT)
+current = await reader.snapshot(WORKER_LIMIT)
+saved = await manager.update(WORKER_LIMIT, 20, expected_version=current.version)
+# saved is SettingSnapshot[int]: name, value, source, version.
+reset = await manager.reset(WORKER_LIMIT, expected_version=saved.version)
+```
+
+This demonstrates an immediate write/reset sequence. Interactive editing must retain the version the operator actually read, rather than fetch a fresh token just before saving. A conflict requires re-reading and a caller decision, not an automatic retry. Application services can also use `self.setting_provider` during managed invocation, not construction. Storage errors propagate; if no allowed source has a value, `snapshot` reports UNSET and `get` fails.
+
+The generated Host selects `SqlAlchemyRuntimeSettingsModule` and `SettingsManagementHttpApiModule`. A custom Host must select them when it needs persistent overrides and management HTTP. Configure its database and run `pddd db upgrade --module settings` as part of database setup; startup does not migrate. Without a store binding, reads can use configuration/defaults but Manager is not registered.
+
+With the default API prefix, use these operations after authenticating and granting the management permissions:
+
+| Operation | Request |
+| --- | --- |
+| List visible settings | `GET /api/settings` |
+| Read a setting and its version | `GET /api/settings/worker.limit` |
+| Save an override | `PUT /api/settings/worker.limit`, body `{"value": 20, "expected_version": "<version from read>"}` |
+| Clear an override | `POST /api/settings/worker.limit/reset`, body `{"expected_version": "<latest version>"}` |
+
+Pass JSON null for `expected_version` only when the read returned null. Reads and writes return `name`, `value`, `source`, and `version`; reset retains a new version token. HTTP 409 means a version conflict. Writes commit independently of the caller's business transaction, and a successful response confirms persistence only.
+
+Definitions may restrict `allowed_sources` without changing their fixed order. Excluding CONFIGURATION rejects matching Host inputs, so remove the YAML/environment setting too. `management_access` defaults to READ_WRITE; READ_ONLY rejects generic writes/reset, while HIDDEN omits the setting from lists and returns not found for individual management operations. Reads require `settings.read`; writes/reset require both `settings.read` and `settings.write`. Optional `read_permission`/`write_permission` values add per-setting requirements: declare those permissions under `domain_shared/permissions`, scan their PermissionDefinitionProvider, and depend on AuthorizationModule. Declaring a permission does not grant it. Internal services own their authorization; Manager still enforces ownership, sources, types, and versions.
+
+Business code decides when to read and apply values. Settings provides no component refresh, change notification, reconciliation, retry, or application status. Generic Notifications and HostedService remain independent capabilities.
+
+### Inspect configuration
 
 Inspect configuration sources and service registrations with:
 

python_ddd_framework/settings/__init__.py

@@ -4,28 +4,23 @@ from .catalog import SettingCatalog
 from .contracts import SettingDefinition, SettingManagementAccess
 from .definitions import SettingDefinitionContext, SettingDefinitionProvider
 from .errors import RuntimeSettingError, SettingDefinitionError
-from .handlers import SettingApplicationStatus, SettingHandler, SettingHandlerDefinition
 from .manager import SettingManager
 from .provider import SettingProvider
 from .store import RuntimeSettingStore
-from .values import SettingSnapshot, SettingValueSource, SettingWriteOutcome, StoredSetting
+from .values import SettingSnapshot, SettingValueSource, StoredSetting
 
 __all__ = (
     "RuntimeSettingError",
     "RuntimeSettingStore",
-    "SettingApplicationStatus",
     "SettingCatalog",
     "SettingDefinition",
     "SettingDefinitionContext",
     "SettingDefinitionError",
     "SettingDefinitionProvider",
-    "SettingHandler",
-    "SettingHandlerDefinition",
     "SettingManagementAccess",
     "SettingManager",
     "SettingProvider",
     "SettingSnapshot",
     "SettingValueSource",
-    "SettingWriteOutcome",
     "StoredSetting",
 )

python_ddd_framework/settings/application.py

@@ -24,7 +24,6 @@ from .management import (
     ResetSettingCommand,
     SettingsManagementApplicationService,
     SettingView,
-    SettingWriteResult,
     UpdateSettingCommand,
 )
 from .manager import SettingManager
@@ -68,7 +67,7 @@ class _SettingsManagementApplicationService(ApplicationService):
         return _view(definition, await self.setting_provider.snapshot(definition))
 
     @authorize(SETTINGS_READ, SETTINGS_WRITE)
-    async def update(self, name: str, command: UpdateSettingCommand) -> SettingWriteResult:
+    async def update(self, name: str, command: UpdateSettingCommand) -> SettingView:
         definition = self._definition(name)
         await self._check_write(definition)
         try:
@@ -79,18 +78,14 @@ class _SettingsManagementApplicationService(ApplicationService):
         saved = await self._settings.update(
             definition, value, expected_version=command.expected_version
         )
-        return SettingWriteResult(
-            setting=_view(definition, saved.snapshot), notification=saved.notification
-        )
+        return _view(definition, saved)
 
     @authorize(SETTINGS_READ, SETTINGS_WRITE)
-    async def reset(self, name: str, command: ResetSettingCommand) -> SettingWriteResult:
+    async def reset(self, name: str, command: ResetSettingCommand) -> SettingView:
         definition = self._definition(name)
         await self._check_write(definition)
         saved = await self._settings.reset(definition, expected_version=command.expected_version)
-        return SettingWriteResult(
-            setting=_view(definition, saved.snapshot), notification=saved.notification
-        )
+        return _view(definition, saved)
 
     def _definition(self, name: str) -> SettingDefinition[Any]:
         definition = self._catalog.get(name)

python_ddd_framework/settings/catalog.py

@@ -4,28 +4,21 @@ from __future__ import annotations
 
 from collections.abc import Iterator, Mapping
 from types import MappingProxyType
-from typing import TYPE_CHECKING, Any
+from typing import Any
 
 from ..diagnostics import SourceLocation
-from ..modularity import ModuleRegistry
 from ..modularity.discovery import _DiscoveredType
 from .contracts import SettingDefinition
-from .declarations import SettingHandlers
 from .definition_discovery import _collect_setting_definitions
 from .errors import SettingDefinitionError
-from .handlers import SettingHandlerDefinition
-
-if TYPE_CHECKING:
-    from ..services.contribution import ServiceContributionRegistry
 
 
 class SettingCatalog:
-    __slots__ = ("_definitions", "_handlers", "_sources")
+    __slots__ = ("_definitions", "_sources")
 
     def __init__(
         self,
         definitions: tuple[SettingDefinition[Any], ...],
-        handlers: tuple[SettingHandlerDefinition[Any], ...] = (),
         *,
         sources: Mapping[str, SourceLocation] | None = None,
     ) -> None:
@@ -45,26 +38,12 @@ class SettingCatalog:
         self._definitions: Mapping[str, SettingDefinition[Any]] = MappingProxyType(
             dict(sorted(indexed.items()))
         )
-        seen: set[tuple[str, type[object]]] = set()
-        for handler in handlers:
-            if not isinstance(handler, SettingHandlerDefinition):
-                raise SettingDefinitionError(setting="handler", reason="invalid handler definition")
-            self.require_owned(handler.setting)
-            key = (handler.setting.name, handler.handler_type)
-            if key in seen:
-                raise SettingDefinitionError(setting=key[0], reason="handler is declared twice")
-            seen.add(key)
-        self._handlers = handlers
         self._sources = MappingProxyType(dict(sources or {}))
 
     @property
     def sources(self) -> Mapping[str, SourceLocation]:
         return self._sources
 
-    @property
-    def handlers(self) -> tuple[SettingHandlerDefinition[Any], ...]:
-        return self._handlers
-
     @property
     def definitions(self) -> tuple[SettingDefinition[Any], ...]:
         return tuple(self._definitions.values())
@@ -83,40 +62,6 @@ class SettingCatalog:
             )
 
 
-def _build_setting_catalog(
-    registry: ModuleRegistry, discoveries: tuple[_DiscoveredType, ...]
-) -> SettingCatalog:
+def _build_setting_catalog(discoveries: tuple[_DiscoveredType, ...]) -> SettingCatalog:
     definitions, sources = _collect_setting_definitions(discoveries)
-    handlers: list[SettingHandlerDefinition[Any]] = []
-    for descriptor, declaration in registry.declarations(SettingHandlers):
-        declared_handlers = declaration.definitions
-        if not isinstance(declared_handlers, tuple):
-            raise SettingDefinitionError(
-                setting=str(descriptor.key), reason="setting_handler_definitions must be a tuple"
-            )
-        handlers.extend(declared_handlers)
-    return SettingCatalog(definitions, tuple(handlers), sources=sources)
-
-
-def _contribute_setting_handler_defaults(
-    registry: ModuleRegistry,
-    contributions: ServiceContributionRegistry,
-) -> None:
-    from dishka import Provider, Scope
-
-    # 声明只拥有 handler 与 setting 的关系；实例和依赖仍交给原生 Dishka APP binding。
-    registered: set[type[object]] = set()
-    for descriptor, declaration in registry.declarations(SettingHandlers):
-        for definition in declaration.definitions:
-            handler_type = definition.handler_type
-            if handler_type in registered:
-                continue
-            registered.add(handler_type)
-            provider = Provider()
-            provider.provide(handler_type, scope=Scope.APP)
-            contributions._add_framework_default(
-                provider=provider,
-                owner=descriptor.key,
-                source=descriptor.declaration_source,
-                reason=f"Settings handler default for {definition.setting.name}",
-            )
+    return SettingCatalog(definitions, sources=sources)

python_ddd_framework/settings/management.py

@@ -2,14 +2,13 @@
 
 from __future__ import annotations
 
-from typing import Literal, Protocol
+from typing import Protocol
 from uuid import UUID
 
 from pydantic import BaseModel, ConfigDict, JsonValue
 
 from ..application_services import ApplicationServiceContract
 from ..authorization import PermissionName
-from ..notifications import NotificationPublishStatus
 from .values import SettingValueSource
 
 SETTINGS_READ = PermissionName("settings.read")
@@ -36,15 +35,6 @@ class SettingView(BaseModel):
     value: JsonValue
     source: SettingValueSource
     version: UUID | None
-    effect: str = "New operations read the saved value; running components apply it separately."
-
-
-class SettingWriteResult(BaseModel):
-    model_config = ConfigDict(frozen=True)
-
-    saved: Literal[True] = True
-    setting: SettingView
-    notification: NotificationPublishStatus
 
 
 class SettingsManagementApplicationService(ApplicationServiceContract, Protocol):
@@ -52,6 +42,6 @@ class SettingsManagementApplicationService(ApplicationServiceContract, Protocol)
 
     async def get(self, name: str) -> SettingView: ...
 
-    async def update(self, name: str, command: UpdateSettingCommand) -> SettingWriteResult: ...
+    async def update(self, name: str, command: UpdateSettingCommand) -> SettingView: ...
 
-    async def reset(self, name: str, command: ResetSettingCommand) -> SettingWriteResult: ...
+    async def reset(self, name: str, command: ResetSettingCommand) -> SettingView: ...

python_ddd_framework/settings/manager.py

@@ -1,32 +1,25 @@
-"""条件写入与提交后通知的 owner；读取解析由 SettingProvider 负责。"""
+"""条件写入的 owner；读取解析由 SettingProvider 负责，生效时机归业务。"""
 
 from __future__ import annotations
 
-import logging
-from typing import TYPE_CHECKING, Any, TypeVar, cast
+from typing import Any, TypeVar, cast
 from uuid import UUID
 
 from pydantic import ValidationError
 from pydantic_core import PydanticSerializationError
 
-from ..notifications import NotificationPayloadError, NotificationPublishStatus, Notifications
 from .catalog import SettingCatalog
-from .changes import SETTINGS_CHANGED, SettingChanged
 from .contracts import SettingDefinition
 from .errors import RuntimeSettingError
 from .provider import SettingProvider
 from .store import RuntimeSettingStore
-from .values import SettingSnapshot, SettingValueSource, SettingWriteOutcome, StoredSetting
-
-if TYPE_CHECKING:
-    from .refresh import SettingsRefreshRuntime
+from .values import SettingSnapshot, SettingValueSource, StoredSetting
 
 _T = TypeVar("_T")
-_LOGGER = logging.getLogger(__name__)
 
 
 class SettingManager:
-    __slots__ = ("_catalog", "_notifications", "_provider", "_refresh", "_store")
+    __slots__ = ("_catalog", "_provider", "_store")
 
     def __init__(
         self, catalog: SettingCatalog, provider: SettingProvider, store: RuntimeSettingStore
@@ -34,13 +27,11 @@ class SettingManager:
         self._catalog = catalog
         self._provider = provider
         self._store = store
-        self._refresh: SettingsRefreshRuntime | None = None
-        self._notifications: Notifications | None = None
 
     async def set_global(self, definition: SettingDefinition[_T], value: _T) -> _T:
         current = await self._provider.snapshot(definition)
         saved = await self.update(definition, value, expected_version=current.version)
-        return cast(_T, saved.snapshot.value)
+        return cast(_T, saved.value)
 
     async def reset_global(self, definition: SettingDefinition[Any]) -> None:
         current = await self._provider.snapshot(definition)
@@ -48,7 +39,7 @@ class SettingManager:
 
     async def update(
         self, definition: SettingDefinition[_T], value: _T, *, expected_version: UUID | None
-    ) -> SettingWriteOutcome[_T]:
+    ) -> SettingSnapshot[_T]:
         self._require_write(definition, operation="set")
         try:
             validated, serialized = definition._dump_json(value)
@@ -60,20 +51,18 @@ class SettingManager:
             definition.name, serialized, expected_version=expected_version
         )
         # 返回本次已经提交的值，不在提交后重读，避免把另一次并发写入误报为本次结果。
-        snapshot = SettingSnapshot(
+        return SettingSnapshot(
             definition.name, validated, SettingValueSource.RUNTIME, saved.version
         )
-        return SettingWriteOutcome(snapshot, await self._committed(definition.name))
 
     async def reset(
         self, definition: SettingDefinition[_T], *, expected_version: UUID | None
-    ) -> SettingWriteOutcome[_T]:
+    ) -> SettingSnapshot[_T]:
         self._require_write(definition, operation="reset")
         # 默认值先校验，不能在物理删除已经提交之后再抛出配置校验失败。
         fallback = self._provider._resolve(definition, StoredSetting(None, expected_version))
         saved = await self._store.write(definition.name, None, expected_version=expected_version)
-        snapshot = SettingSnapshot(definition.name, fallback.value, fallback.source, saved.version)
-        return SettingWriteOutcome(snapshot, await self._committed(definition.name))
+        return SettingSnapshot(definition.name, fallback.value, fallback.source, saved.version)
 
     def _require_write(self, definition: SettingDefinition[Any], *, operation: str) -> None:
         self._catalog.require_owned(definition)
@@ -81,16 +70,3 @@ class SettingManager:
             raise RuntimeSettingError(
                 setting=definition.name, operation=operation, error_type="SourceNotAllowed"
             )
-
-    async def _committed(self, name: str) -> NotificationPublishStatus:
-        # 本地刷新先入队；Redis 降级不会撤销短事务已经提交的结果。
-        if self._refresh is not None:
-            self._refresh.request_refresh(name)
-        if self._notifications is None:
-            return NotificationPublishStatus.NOT_CONFIGURED
-        try:
-            return await self._notifications.publish(SETTINGS_CHANGED, SettingChanged(name=name))
-        except NotificationPayloadError:
-            # 发布大小/编码限制是独立结果；不能把已提交的写入重新表现为保存失败。
-            _LOGGER.warning("Committed setting notification rejected for %s", name)
-            return NotificationPublishStatus.REJECTED

python_ddd_framework/settings/module.py

@@ -8,11 +8,10 @@ from ..modularity import AppModule, ModuleRef
 from ..services.composition import (
     ServiceBindingContext,
     ServiceComposition,
-    ServiceDiscoveryContext,
 )
 from ..services.registration import RegistrationDecision, RegistrationKind
 from .binding import _provide_settings
-from .catalog import SettingCatalog, _build_setting_catalog, _contribute_setting_handler_defaults
+from .catalog import SettingCatalog, _build_setting_catalog
 from .errors import SettingDefinitionError
 from .store import RuntimeSettingStore
 
@@ -21,15 +20,10 @@ class SettingsModule(AppModule):
     catalog: SettingCatalog
 
     def configure(self, context: ConfigureContext) -> None:
-        self.catalog = _build_setting_catalog(context.modules, context.discoveries)
+        self.catalog = _build_setting_catalog(context.discoveries)
         if self.catalog.definitions:
             context.configure.section("settings")
-        context.services.add_composition(
-            ServiceComposition(discover=self._discover, bind=self._bind)
-        )
-
-    def _discover(self, context: ServiceDiscoveryContext) -> None:
-        _contribute_setting_handler_defaults(context.modules, context.services)
+        context.services.add_composition(ServiceComposition(bind=self._bind))
 
     def _bind(self, context: ServiceBindingContext) -> None:
         provider = Provider()

python_ddd_framework/settings/values.py

@@ -7,8 +7,6 @@ from enum import Enum
 from typing import Generic, TypeVar
 from uuid import UUID
 
-from ..notifications import NotificationPublishStatus
-
 _T = TypeVar("_T")
 
 
@@ -31,9 +29,3 @@ class SettingSnapshot(Generic[_T]):
     value: _T | None
     source: SettingValueSource
     version: UUID | None
-
-
-@dataclass(frozen=True, slots=True)
-class SettingWriteOutcome(Generic[_T]):
-    snapshot: SettingSnapshot[_T]
-    notification: NotificationPublishStatus

{python_ddd_framework-0.8.0.dist-info → python_ddd_framework-0.9.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: python-ddd-framework
-Version: 0.8.0
+Version: 0.9.0
 Summary: Modular DDD application framework with project CLI and bundled templates
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
@@ -64,7 +64,7 @@ Python DDD Framework combines a module system with FastAPI, Dishka, Pydantic, SQ
 | HTTP APIs | Expose selected application services through FastAPI, or write explicit routers. Use OpenAPI, filters, file uploads, downloads, and streaming responses. |
 | Persistence and events | Use async SQLAlchemy repositories, explicit transaction boundaries, module-owned Alembic migrations, seed contributors, and local events before or after commit. |
 | Identity and permissions | Add JWT authentication, refresh sessions, users and roles, permission definitions, and authorization on service methods. |
-| Cache, settings, and locks | Use typed Redis caching, runtime settings with conditional updates and reset, settings refresh notifications, and explicit Redis-backed business locks. |
+| Cache, settings, and locks | Use typed Redis caching, global runtime settings with conditional updates and reset, and explicit Redis-backed business locks. |
 | Background execution | Enqueue durable PostgreSQL jobs with typed payloads, schedule recurring work, run periodic workers, and select in-process or managed subprocess execution. |
 | Real-time communication | Add authenticated WebSocket connections, typed messages, and targeted notifications to connected clients. |
 | Hosting and observability | Manage long-lived integrations with `HostedService`, coordinate shutdown, and use structured logging, correlation, OpenTelemetry tracing, and lifecycle health endpoints. |
@@ -273,6 +273,12 @@ Edit `backend/app.development.yaml` for local connections, identity settings, lo
 
 Generated credentials are for local development. Production configuration is supplied separately in `app.production.yaml`. See [configuration](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/development.md#定义-module-与配置) and [background and logging configuration](https://github.com/componet-architecture/python-ddd-framework/blob/main/docs/development.md#settings后台与日志).
 
+### Use global settings
+
+Declare a typed `SettingDefinition` and its scanned provider under the owning module's `domain/settings/`, then add `SettingsModule` to that module's dependencies. Inject `SettingProvider` to read values and `SettingManager` for conditional writes/reset. The generated Host already selects Settings persistence and management HTTP; apply its Settings migration before using the store for reads or writes.
+
+Values resolve from runtime override, Host configuration, then definition default. Reset clears an override and resumes fallback. Management provides list/read/update/reset with visibility, permissions, and version checks; business code decides when to use the value. Follow the [complete project recipe](docs/development.md#settings-策略与使用) or the generated project's **Global settings** guide for declarations, configuration, permissions, and request bodies. The minimal contract starts with 0.9.0; see [migration notes](#minimal-settings-migration-090).
+
 ### Run application tests
 
 After completing local database setup, run from `backend/`:
@@ -314,6 +320,16 @@ New `ddd` modules contain the full responsibility directories and necessary comp
 
 See the [migration guide](docs/development.md#数据库聚合与迁移) and [verification record](docs/status.md#http-回收与迁移来源判定未发布).
 
+## Minimal Settings migration (0.9.0)
+
+Settings now owns only global definitions, reads, writes, and clearing overrides. Modules own definitions, the Host selects storage, and business code decides when and how to use the values. Source order, source restrictions, management permissions, typed JSON, independent transactions, UUID concurrency tokens, and reset version records remain unchanged. No dependency, database schema, or migration change is required.
+
+- Remove `SettingsRefreshModule`, `SettingsNotificationsModule`, `SettingHandlers`, `SettingHandlerDefinition`, and Settings refresh options from Host/module wiring. Remove settings observers and the dedicated `application/setting_handlers` directory. Read through `SettingProvider` where the business needs the value; the framework no longer coordinates application, polling, reconnect compensation, retries, or application status. Generic Notifications and HostedService remain available independently.
+- `SettingManager.update/reset` returns `SettingSnapshot[T]` directly: replace `result.snapshot.value/version` with `result.value/version`. `SettingWriteOutcome`, notification feedback, and handler/application status exports are removed.
+- HTTP update/reset returns the same `SettingView` shape as a read: `name`, `value`, `source`, and `version`. Replace `response.setting` with `response`; remove `saved`, `notification`, and `effect` handling. `SettingWriteResult` is removed. Success confirms persistence only, and stale versions still produce a conflict.
+
+Current rules and examples are in the [Settings contract](docs/architecture.md#typed-cache-与-settings) and [usage guide](docs/development.md#settings-策略与使用). Validation and remaining limits are recorded in [status](docs/status.md#settings-最小化未发布).
+
 ## Settings policies (0.8.0)
 
 `SettingDefinition` now accepts `allowed_sources`, `management_access`, `read_permission`, and `write_permission`. Existing definitions retain their source order and management visibility. Generic update/reset now also require `settings.read`, in addition to `settings.write` and any declared per-setting permissions, because their responses contain the saved setting snapshot. Update roles that previously held only write permission.
@@ -351,7 +367,7 @@ Runnable examples: [HTTP generators](docs/development.md#http-生成器与持续
 Capability composition now uses the same `AppModule` model as customer modules. Existing applications must migrate their declarations together; there is no compatibility path.
 
 - Declare capability dependencies on the Module that uses them. Selecting a sibling provider in Host does not supply a missing business-module dependency. `ApplicationServicesModule` supplies the usual application-service capabilities; additional capabilities are explicit dependencies.
-- Wrap capability declarations with `NotificationDefinitions`, `HostedServices`, `BackgroundWorkers`, `BackgroundSchedules`, or `SettingHandlers` from their owning packages. Use native service registration for providers and `ServiceComposition` for capability discovery and final binding. Keep provider selection in Host.
+- Wrap capability declarations with `NotificationDefinitions`, `HostedServices`, `BackgroundWorkers`, or `BackgroundSchedules` from their owning packages. Use native service registration for providers and `ServiceComposition` for capability discovery and final binding. Keep provider selection in Host.
 - Replace Application invocation methods with `invoke(application, Service.method, ...)`, `invoke_as(application, user, ...)`, `call(application, function, ...)`, and `call_as(application, user, ...)`. Register interception with `add_interceptor(context, ...)` and events with `subscribe_local_event(context, ...)`. Import these functions from `python_ddd_framework`.
 - Read capability catalogs from their Module instance through `application.modules.instance(ModuleType)` or the catalog's DI binding. Generic service diagnostics remain in `application.service_catalog`; readiness is `application.is_ready`.
 - `DataSeedContributor`, `DataSeeder`, and `DataSeedError` belong to `python_ddd_framework.seeding` and remain available from the root package. Domain Modules with contributors depend on `DataSeedingModule`; remove `@application_service` from contributors. Seed is no longer an ApplicationService or part of its catalog. Explicit seed commands retain contributor ordering, per-item UoW, module dependency selection, failure reporting, and cleanup.

{python_ddd_framework-0.8.0.dist-info → python_ddd_framework-0.9.0.dist-info}/RECORD

@@ -1,4 +1,4 @@
-python_ddd_framework/__init__.py,sha256=P4vRQIXbhDQk8zp_5_ToXK2lRJdPLUvAZ8iC-t6bg7U,15476
+python_ddd_framework/__init__.py,sha256=TuNv1DOY2PLAvwzWzj_j0zSoJmofjjkdOQdqY18SDwI,15402
 python_ddd_framework/application/__init__.py,sha256=RPe_lkegIRim7GcBnXyevOg5KM7bfUIO9YGsqcA0lXk,184
 python_ddd_framework/application/build_spec.py,sha256=Udj1JIgP2oBMCUezmzWzOdjFYBCEE8OxwHSEaDqrMMo,1030
 python_ddd_framework/application/builder.py,sha256=d0vc1D5HvG_aJI5lPQydr-ha0OTNviWlplxlyP99qDs,8080
@@ -107,7 +107,7 @@ python_ddd_framework/developer_kit/templates/basic/{{cookiecutter.module_name}}/
 python_ddd_framework/developer_kit/templates/basic/{{cookiecutter.module_name}}/services/__init__.py.jinja,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 python_ddd_framework/developer_kit/templates/basic/{{cookiecutter.module_name}}/services/default_conversion_service.py.jinja,sha256=YIYXqDycBVoUlLCwwUZ2tcyUk2fKSu-20mI00u5QUhc,342
 python_ddd_framework/developer_kit/templates/module/cookiecutter.json,sha256=edD_zSqmFuOKvMZyxmFFabAavBQJk0tbGO4YrnsgZN0,60
-python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/README.md,sha256=bojfHi_8PIPSeJheOdS6hSIaG2LrXDwmqymnwm0ZPDs,5674
+python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/README.md,sha256=nbPgBhWynTZaK6vojFyxf2ARSYAzw6xCsNzAqUtulNo,6537
 python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/__init__.py.jinja,sha256=byPOI4PKtQDi5IQa9tzZZEVYy5zGx9PJdBzPrgcxm64,89
 python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/__init__.py.jinja,sha256=pm9_TqjN20deRELpopxK412O3mra0OZ6QdesPdcsaRU,90
 python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/background_jobs/__init__.py.jinja,sha256=Kbig4VsdpmVUDHx5SLPf7ZZM6S5ftVmzBxBAJIjwvng,40
@@ -120,7 +120,6 @@ python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}
 python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/module.py.jinja,sha256=qGmq1ggBmxGY2B8H8gB8tEY-uxMuWpyr60l0ZAouho8,1950
 python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/options/__init__.py.jinja,sha256=Kbig4VsdpmVUDHx5SLPf7ZZM6S5ftVmzBxBAJIjwvng,40
 python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/services/__init__.py.jinja,sha256=Kbig4VsdpmVUDHx5SLPf7ZZM6S5ftVmzBxBAJIjwvng,40
-python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/setting_handlers/__init__.py.jinja,sha256=Kbig4VsdpmVUDHx5SLPf7ZZM6S5ftVmzBxBAJIjwvng,40
 python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/__init__.py.jinja,sha256=grSDmU4IKdRYZsqi56aEVvsgx92AYF2k3jlDzANqra4,51
 python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/inputs/__init__.py.jinja,sha256=Kbig4VsdpmVUDHx5SLPf7ZZM6S5ftVmzBxBAJIjwvng,40
 python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application_contracts/integration_services/__init__.py.jinja,sha256=Kbig4VsdpmVUDHx5SLPf7ZZM6S5ftVmzBxBAJIjwvng,40
@@ -158,8 +157,8 @@ python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}
 python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/repositories/__init__.py.jinja,sha256=VdqphDwvoB9nhl5Q9vHpSnmMWwDUlDp_YckRkionwWw,46
 python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/tests/__init__.py.jinja,sha256=Kbig4VsdpmVUDHx5SLPf7ZZM6S5ftVmzBxBAJIjwvng,40
 python_ddd_framework/developer_kit/templates/project/cookiecutter.json,sha256=vmN799k9eRHAEGeYt8uUjPsusbblvgpNIsXVOsXUno4,314
-python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/AGENTS.md,sha256=u4fnjZJgqmIGf2CI9yYNRsfDLFktvGvuOVm2M-DQmKs,13059
-python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/README.md,sha256=i65NyuY-MXu1eZ3M_Ob5hFpcqCSd8hzc3iYr3Cn27g4,11146
+python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/AGENTS.md,sha256=MVG6FbJckCZYwq-V33AZpH7RCvcv2tKaaN5VcaIzJ6M,13432
+python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/README.md,sha256=y_Xg7rKtj6I8U2ChoLj57C5jz75gk2BdqD8F-ZH8IfI,11874
 python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/backend/.dockerignore,sha256=TG053vIzikxG8h53vCcU_s5wcr7p4GEKwsedbrRrSOo,71
 python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/backend/.gitignore,sha256=OF6nwgb-RiP8EAXc5osbk3bsOEYkk0JaV99v3FcglTU,66
 python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/backend/.python-version,sha256=lN0hZ-3c-Wk_uFRrQasUfy9YJrXrdvSzYKhuHeXIXbY,34
@@ -170,11 +169,11 @@ python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name
 python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/backend/pyproject.toml.jinja,sha256=zZ-kDjgfOYo4g35VLoctEEoyvlZm9fEB2ddHW30JzUs,932
 python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/backend/src/host/__init__.py.jinja,sha256=RfLT7dqPnSotCDorSp6Taz9jBYOmepu6De_wZNelWZ8,74
 python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/backend/src/host/main.py.jinja,sha256=SPxJ86SW1dx-BuoWITWifq-6NseoxnVMLTufcFFsxF4,1996
-python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/backend/src/host/module.py.jinja,sha256=6j63muRR7tQmYIFso-egk8L5_Zw57I61ijWR8SDpw5U,3235
+python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/backend/src/host/module.py.jinja,sha256=qpM0L69ek8-SXQpJoZ-NkPyfGGIGTRrB1xtrmzpxZF8,3004
 python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/backend/tests/conftest.py.jinja,sha256=I_SlSxioBsCFNJLM52iM-neYBJR71qOUn7C4dI9t-7I,149
 python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/backend/tests/host/test_http.py.jinja,sha256=pmiz6k0oWWrPeW_rVG2Ynibg4j3yuKvgvYFc0K7J_no,2766
-python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/architecture.md,sha256=qU6lE4iwhTUDCY3OvtSgNYw99k8JGaOsyrmdaFt_Py4,26920
-python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/development.md,sha256=hEn_ucr8NmZnEp80TyAYB1IoLMWUoh9Hk8wCBzCizDM,53182
+python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/architecture.md,sha256=VINiboJya5Ae6wn0UL7pHK-IXX7OIKfI0jbWaOL0F9U,27842
+python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/development.md,sha256=V44TFV5BU5dhCautVc8D41h2-QhKgyCk69X3d-dWZgk,57556
 python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/scripts/.gitkeep,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 python_ddd_framework/developer_kit/wiring.py,sha256=80ZhxpGXK6NP3b_BTTc1kt3oIU21MU70cT9kgm8ZgAE,7835
 python_ddd_framework/diagnostics/__init__.py,sha256=HdgzjQqMJ_SUGKJc5EcQ5PL1rM4GcTeem-L0q1r7vjQ,455
@@ -390,25 +389,19 @@ python_ddd_framework/services/registration.py,sha256=AsvhVv_szq8TcaXdUMvOY6fNNp8
 python_ddd_framework/services/relocation.py,sha256=oMel_8RPFtPHDE9KrUepzx1nJpiug0EaNK7RWEKZFC0,3763
 python_ddd_framework/services/repository.py,sha256=jjjCmpcz4deAZmDNSM44WlDmh9msFO53qN116CHdBSM,1686
 python_ddd_framework/services/runtime.py,sha256=57G5jNjOiexpSqTCogdI18u5xeEK2YglztNqDtFcsZI,9300
-python_ddd_framework/settings/__init__.py,sha256=j9byBRTyegmIEK1KD6Q3UkHurPCnMUYJdnlhXTWL_wo,1090
-python_ddd_framework/settings/application.py,sha256=3hAlheeHcwSIS_1bFQmv7qjsAMIk7JYq9LnQLITfOWk,5666
+python_ddd_framework/settings/__init__.py,sha256=EYm9Ek57X2o1edniVeKn150uKFgSrHF7onKUncGRQnc,867
+python_ddd_framework/settings/application.py,sha256=QMouHpNJUxkmkQ3kRHSxtZ4ssDAsRZitYWiWADuGCH4,5444
 python_ddd_framework/settings/binding.py,sha256=_wDIsKe-p6WuKaQB9NvhbxCm9aYbiN95m7erJS35T8Y,1621
-python_ddd_framework/settings/catalog.py,sha256=fqVeFr3DuJWrNUfIuIwfivVhuCobQpWe32EmRieuUVE,4880
-python_ddd_framework/settings/changes.py,sha256=zpHhCJY83s-KIs7NkjQAmIxzY7cJfT8FD4A08gF9NfE,367
+python_ddd_framework/settings/catalog.py,sha256=IkfZTd2PGUOMTyW7koQEdIXqPdiiPYlNmoTyfxPF4P0,2452
 python_ddd_framework/settings/contracts.py,sha256=v_Wn7kr3_JQYH-rXeusR_YWvtwR3RT_KxQqnvVD7uZI,6899
-python_ddd_framework/settings/declarations.py,sha256=FeFrgw6fAdjX6bGaajjnO2tsrfxEvKW6sZrRfTAxCEs,526
 python_ddd_framework/settings/definition_discovery.py,sha256=zHN3-coqzdEb--mecv00v7ifWzzCfJRZ-BrFcdVx4u4,3002
 python_ddd_framework/settings/definitions.py,sha256=hkWO0dqOoBmd7pKv-cUsCZaEU0AeUEULVLW1Rl8uwdQ,1687
 python_ddd_framework/settings/errors.py,sha256=ZcU1nMB44_Rq9Wl5bw83s3Y066LxSLrFqOW_gG6ViS4,836
-python_ddd_framework/settings/handlers.py,sha256=A0GWDKRXASlCoWm_Wduul0thAv4xW4SG305KXd6wY-4,1369
-python_ddd_framework/settings/management.py,sha256=dJhyZYfNA5Qsup9yt2dKOrIwGq3OnNkDxskJniBV3BI,1656
-python_ddd_framework/settings/manager.py,sha256=5pWLFB7EHMUsqnz-Gy615A2Sxv0HsKIEQtgmm0zl70A,4561
-python_ddd_framework/settings/module.py,sha256=KQydGp507MUlcykRWVUa36r5-_--BRJn88QLirxotAI,3340
-python_ddd_framework/settings/notifications.py,sha256=tVSXjhhJWhkMcOakSmeOfXT1X02Hcx2xRU8Whr8rSig,1700
+python_ddd_framework/settings/management.py,sha256=sfibyZzhrsYg8FwPZCz_mDw6UEBtnP9HJaVu2O8PMmc,1298
+python_ddd_framework/settings/manager.py,sha256=0jc7dQxGgKY-vc3rzVrPevHPZ6BY7y4APaxGd74kKlk,3164
+python_ddd_framework/settings/module.py,sha256=jnCyeiFAnQB2q3Zeyx-HN9xmHbpGouUrfB3K3gJ8ekE,3061
 python_ddd_framework/settings/permissions.py,sha256=2nPyZOZ9G-4mSCIqwNI0C9WUBhP0ZwqNjljP3XZD3PE,553
 python_ddd_framework/settings/provider.py,sha256=AvMrdWML_wbbJEqNb9IH8_OcUUX8QbdEpxw4GDibdA4,3216
-python_ddd_framework/settings/refresh.py,sha256=jYYqEdTU4cOXyHmdMEdw_94qybp4bzVPRdrM6WF8q6k,5413
-python_ddd_framework/settings/refresh_module.py,sha256=wDxWau4oZCtBiMO6TDXZFbZRcKTiYaTFGWPjZnaFNug,2225
 python_ddd_framework/settings/sqlalchemy/__init__.py,sha256=G-S-sSsxwfjZxr0mVAyXUBG0SIxC3ZCMtrdpMsZ14YM,158
 python_ddd_framework/settings/sqlalchemy/migrations/0001_settings.py,sha256=wx_GcxijY-43V9DoNNzdvfwg8d5oYWkmeWSe23xtXLA,1045
 python_ddd_framework/settings/sqlalchemy/migrations/0002_physical_delete.py,sha256=JtPmESosI_SIe4ijFuBFX7zvcgsnk-7dtjULipdC6NU,982
@@ -418,7 +411,7 @@ python_ddd_framework/settings/sqlalchemy/models.py,sha256=qKbRHhdm0uDPUUtLgeVeFv
 python_ddd_framework/settings/sqlalchemy/module.py,sha256=NbvxE40aSW1aWf7CbU3GRPN_WrvsQgUXp05hAAoDtcE,1212
 python_ddd_framework/settings/sqlalchemy/store.py,sha256=I9yRtpZBzNEYG0NANFAgVvVTY0_Qnl5JinXf00ebQwE,3597
 python_ddd_framework/settings/store.py,sha256=3tdF-0l0owUdWuNEd0K8OfbXncI38hx0pD6anU5GdmA,442
-python_ddd_framework/settings/values.py,sha256=KMRZDQu2FRNXDIdJwGVgHn656Hc5qRY2WQGjbBxfhO4,898
+python_ddd_framework/settings/values.py,sha256=smw2jLySVP6aKefqmkOqHp8z9pjc2nGfEofE6uGzMZY,687
 python_ddd_framework/sqlalchemy/__init__.py,sha256=DP6PAJHevoc1i-n9ma8_2CAiPmAvWoN7opqRYzHR4Sg,2054
 python_ddd_framework/sqlalchemy/alembic_runtime/__init__.py,sha256=r-ZHMiEhca5M2xv3plW9U3fHfzt5lVQeDohEFqrTuv0,82
 python_ddd_framework/sqlalchemy/alembic_runtime/env.py,sha256=ArKiDG9n5JOPQG44oSrJUd3o96zyY-b2PPkGysFy674,1389
@@ -452,9 +445,9 @@ python_ddd_framework/unit_of_work/module.py,sha256=EjsUtCG7w56NmLU_xqBRiwJ65Mw5h
 python_ddd_framework/unit_of_work/options.py,sha256=AVcEmwwn39qvj8PLQetBeGzdU_eblABGuNLDIQU5tyI,3365
 python_ddd_framework/validation/__init__.py,sha256=nTN_BgIXMLHeUtMgSj2hpisWc1_sk6UWTapk30oh1us,100
 python_ddd_framework/validation/models.py,sha256=Ydz5ZYgqYMPZEXi9A3DA6beN5lD9AcMaImnxDf1aRXs,1737
-python_ddd_framework-0.8.0.dist-info/licenses/LICENSE,sha256=2sSWLZdtk4EhG2GlwpksXzmyux-G6Qiov0D27lE_bqw,805
-python_ddd_framework-0.8.0.dist-info/licenses/src/python_ddd_framework/background_jobs/pgqueuer/UPSTREAM_LICENSE.txt,sha256=0lCGUd5Pke2Up1Kqn1kRnHcwLlBz60E8xvR7WL4k_kE,1066
-python_ddd_framework-0.8.0.dist-info/WHEEL,sha256=si2p8vW03RnhyBnhWl4tj-ObJa78SpE-c9HsEtblGR0,80
-python_ddd_framework-0.8.0.dist-info/entry_points.txt,sha256=CMy4XBD8IKGUfHwe0YBmHmSJtjfnA3yyDHqsMZCLsc8,447
-python_ddd_framework-0.8.0.dist-info/METADATA,sha256=IbP9K_ypVhMhck9GNfdMSwDRTeyqV_Muvph0XxBUDDY,68850
-python_ddd_framework-0.8.0.dist-info/RECORD,,
+python_ddd_framework-0.9.0.dist-info/licenses/LICENSE,sha256=2sSWLZdtk4EhG2GlwpksXzmyux-G6Qiov0D27lE_bqw,805
+python_ddd_framework-0.9.0.dist-info/licenses/src/python_ddd_framework/background_jobs/pgqueuer/UPSTREAM_LICENSE.txt,sha256=0lCGUd5Pke2Up1Kqn1kRnHcwLlBz60E8xvR7WL4k_kE,1066
+python_ddd_framework-0.9.0.dist-info/WHEEL,sha256=si2p8vW03RnhyBnhWl4tj-ObJa78SpE-c9HsEtblGR0,80
+python_ddd_framework-0.9.0.dist-info/entry_points.txt,sha256=CMy4XBD8IKGUfHwe0YBmHmSJtjfnA3yyDHqsMZCLsc8,447
+python_ddd_framework-0.9.0.dist-info/METADATA,sha256=hk9U10YzJOgUMz5XK2ZTFvqjAwrhoBquHOzoMXqJQgI,71605
+python_ddd_framework-0.9.0.dist-info/RECORD,,

python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/application/setting_handlers/__init__.py.jinja

@@ -1 +0,0 @@
-"""所属能力的实现或契约。"""

python_ddd_framework/settings/changes.py

@@ -1,14 +0,0 @@
-"""Settings 变更只通知标识，数据库仍是有效值的唯一权威。"""
-
-from pydantic import BaseModel, ConfigDict
-
-from ..notifications import NotificationDefinition
-
-
-class SettingChanged(BaseModel):
-    model_config = ConfigDict(frozen=True, extra="forbid")
-
-    name: str
-
-
-SETTINGS_CHANGED = NotificationDefinition("settings.changed", SettingChanged)

python_ddd_framework/settings/declarations.py

@@ -1,18 +0,0 @@
-"""Settings handler 的关系声明；实例和生命周期仍由原生 DI 管理。"""
-
-from dataclasses import dataclass
-from typing import Any
-
-from ..modularity import AppModule, ModuleDeclaration
-from .handlers import SettingHandlerDefinition
-
-
-@dataclass(frozen=True, slots=True)
-class SettingHandlers(ModuleDeclaration):
-    definitions: tuple[SettingHandlerDefinition[Any], ...]
-
-    @property
-    def required_module(self) -> type[AppModule]:
-        from .module import SettingsModule
-
-        return SettingsModule

python_ddd_framework/settings/handlers.py

@@ -1,43 +0,0 @@
-"""长期组件的 typed 应用契约；执行上下文由组件自身负责。"""
-
-from __future__ import annotations
-
-import inspect
-from dataclasses import dataclass
-from typing import Generic, Protocol, TypeVar
-
-from .contracts import SettingDefinition
-from .errors import SettingDefinitionError
-from .values import SettingSnapshot
-
-_T = TypeVar("_T")
-
-
-class SettingHandler(Protocol[_T]):
-    async def apply(self, snapshot: SettingSnapshot[_T]) -> None: ...
-
-
-@dataclass(frozen=True, slots=True)
-class SettingHandlerDefinition(Generic[_T]):
-    setting: SettingDefinition[_T]
-    handler_type: type[SettingHandler[_T]]
-
-    def __post_init__(self) -> None:
-        if not isinstance(self.setting, SettingDefinition):
-            raise SettingDefinitionError(setting="handler", reason="setting must be a definition")
-        if (
-            not isinstance(self.handler_type, type)
-            or inspect.isabstract(self.handler_type)
-            or not inspect.iscoroutinefunction(getattr(self.handler_type, "apply", None))
-        ):
-            raise SettingDefinitionError(
-                setting=self.setting.name, reason="handler must have an async apply method"
-            )
-
-
-@dataclass(frozen=True, slots=True)
-class SettingApplicationStatus:
-    setting: str
-    handler: str
-    last_applied: SettingSnapshot[object] | None
-    error_type: str | None

python_ddd_framework/settings/notifications.py

@@ -1,41 +0,0 @@
-"""Settings 是通用通知的使用方，重连和漏消息的补偿由 Settings 自身拥有。"""
-
-from __future__ import annotations
-
-from contextlib import AsyncExitStack
-
-from ..lifecycle import PreInitializeContext, ShutdownContext
-from ..modularity import AppModule
-from ..notifications import Notifications
-from ..notifications.declarations import NotificationDefinitions
-from ..notifications.module import NotificationsModule
-from .changes import SETTINGS_CHANGED, SettingChanged
-from .manager import SettingManager
-from .refresh import SettingsRefreshRuntime
-from .refresh_module import SettingsRefreshModule
-
-
-class SettingsNotificationsModule(AppModule):
-    dependencies = (SettingsRefreshModule, NotificationsModule)
-    notification_definitions = NotificationDefinitions((SETTINGS_CHANGED,))
-
-    def __init__(self) -> None:
-        self._subscriptions = AsyncExitStack()
-
-    async def pre_initialize(self, context: PreInitializeContext) -> None:
-        refresh = await context.container.get(SettingsRefreshRuntime)
-        notifications = await context.container.get(Notifications)
-        settings = await context.container.get(SettingManager)
-
-        async def changed(message: SettingChanged) -> None:
-            refresh.request_refresh(message.name)
-
-        await self._subscriptions.enter_async_context(
-            notifications.subscribe(SETTINGS_CHANGED, changed, on_reconnect=refresh.request_refresh)
-        )
-        settings._notifications = notifications
-
-    async def shutdown(self, context: ShutdownContext) -> None:
-        settings = await context.container.get(SettingManager)
-        settings._notifications = None
-        await self._subscriptions.aclose()

python_ddd_framework/settings/refresh.py

@@ -1,140 +0,0 @@
-"""单进程 Settings 刷新 owner：合并读取、串行应用、失败后按周期重试。"""
-
-from __future__ import annotations
-
-import asyncio
-import logging
-from contextlib import suppress
-from dataclasses import dataclass
-from typing import Any, ClassVar
-
-from pydantic import ConfigDict, Field
-
-from ..hosted_services import HostedService, HostedServiceContext
-from ..invocation.runtime import _InvocationRuntime
-from ..lifecycle import ShutdownReason
-from ..observability.context import capture_trace_context, invocation_span
-from ..options import BaseOptions, Options
-from .contracts import SettingDefinition
-from .handlers import SettingApplicationStatus, SettingHandler
-from .provider import SettingProvider
-from .values import SettingSnapshot, SettingValueSource
-
-_LOGGER = logging.getLogger(__name__)
-
-
-class SettingsRefreshOptions(BaseOptions):
-    model_config = ConfigDict(extra="forbid")
-
-    reconciliation_interval_seconds: float = Field(default=30.0, gt=0)
-
-
-@dataclass(slots=True)
-class _ApplicationRecord:
-    handler: SettingHandler[Any]
-    last_applied: SettingSnapshot[Any] | None = None
-    error_type: str | None = None
-
-
-class SettingsRefreshRuntime(HostedService):
-    run_in_background_processes: ClassVar[bool] = True
-
-    def __init__(
-        self,
-        settings: SettingProvider,
-        options: Options[SettingsRefreshOptions],
-        runtime: _InvocationRuntime,
-    ) -> None:
-        self._settings = settings
-        self._options = options.value
-        self._runtime = runtime
-        self._definitions: dict[str, SettingDefinition[Any]] = {}
-        self._records: dict[str, list[_ApplicationRecord]] = {}
-        self._dirty: dict[str, dict[str, str]] = {}
-        self._wakeup = asyncio.Event()
-        self._task: asyncio.Task[None] | None = None
-
-    def _register(self, definition: SettingDefinition[Any], handler: SettingHandler[Any]) -> None:
-        self._definitions[definition.name] = definition
-        self._records.setdefault(definition.name, []).append(_ApplicationRecord(handler))
-
-    def request_refresh(self, name: str | None = None) -> None:
-        if name is None:
-            for key in self._definitions:
-                self._dirty.setdefault(key, {})
-        elif name in self._definitions:
-            self._dirty[name] = capture_trace_context(self._runtime.tracer)
-        if self._dirty:
-            self._wakeup.set()
-
-    @property
-    def statuses(self) -> tuple[SettingApplicationStatus, ...]:
-        return tuple(
-            SettingApplicationStatus(
-                name,
-                f"{type(record.handler).__module__}.{type(record.handler).__qualname__}",
-                record.last_applied,
-                record.error_type,
-            )
-            for name, records in self._records.items()
-            for record in records
-        )
-
-    async def start(self, context: HostedServiceContext) -> None:
-        self.request_refresh()
-        self._task = asyncio.create_task(self._run(), name=context.name)
-
-    async def stop(self, reason: ShutdownReason) -> None:
-        if self._task is not None:
-            self._task.cancel()
-            with suppress(asyncio.CancelledError):
-                await self._task
-
-    async def _run(self) -> None:
-        if not self._definitions:
-            await asyncio.Future[None]()
-        while True:
-            try:
-                await asyncio.wait_for(
-                    self._wakeup.wait(), timeout=self._options.reconciliation_interval_seconds
-                )
-            except TimeoutError:
-                self.request_refresh()
-            # 取走本轮名字后立即清理；await 期间到达的新请求进入下一轮，不能被误清除。
-            requests = tuple(self._dirty.items())
-            self._dirty.clear()
-            self._wakeup.clear()
-            for name, carrier in requests:
-                with invocation_span(
-                    self._runtime.tracer, f"refresh setting {name}", carrier=carrier
-                ):
-                    await self._refresh(name)
-
-    async def _refresh(self, name: str) -> None:
-        try:
-            latest = await self._settings.snapshot(self._definitions[name])
-        except Exception as error:
-            for record in self._records[name]:
-                record.error_type = type(error).__name__
-            _LOGGER.error("Settings refresh failed for %s: %s", name, type(error).__name__)
-            return
-        for record in self._records[name]:
-            previous = record.last_applied
-            if (
-                previous is not None
-                and record.error_type is None
-                and previous.value == latest.value
-                and (previous.source is SettingValueSource.UNSET)
-                == (latest.source is SettingValueSource.UNSET)
-            ):
-                continue
-            try:
-                with invocation_span(self._runtime.tracer, f"apply setting {name}"):
-                    await record.handler.apply(latest)
-            except Exception as error:
-                # 失败不能覆盖成功记录，下一次校对仍会按最后成功应用的值决定重试。
-                record.error_type = type(error).__name__
-                _LOGGER.error("Settings handler failed for %s: %s", name, record.error_type)
-            else:
-                record.last_applied = latest
-                record.error_type = None

python_ddd_framework/settings/refresh_module.py

@@ -1,52 +0,0 @@
-"""只组装正式 handler 与刷新运行时；组件应用规则由 handler 自己拥有。"""
-
-from __future__ import annotations
-
-from dishka import DEFAULT_COMPONENT, DependencyKey
-
-from python_ddd_framework import ConfigureContext
-
-from ..hosted_services.declarations import HostedServices
-from ..lifecycle import PreInitializeContext, ShutdownContext
-from ..modularity import AppModule, ModuleRef
-from .catalog import SettingCatalog
-from .manager import SettingManager
-from .module import SettingsModule
-from .refresh import SettingsRefreshOptions, SettingsRefreshRuntime
-
-
-class SettingsRefreshModule(AppModule):
-    dependencies = (
-        SettingsModule,
-        ModuleRef("python_ddd_framework.hosted_services.module:HostedServicesModule"),
-    )
-
-    def __init__(self) -> None:
-        self._manager: SettingManager | None = None
-
-    def configure(self, context: ConfigureContext) -> None:
-        context.configure(SettingsRefreshOptions, section="settings_refresh")
-
-    hosted_services = HostedServices((SettingsRefreshRuntime,))
-
-    async def pre_initialize(self, context: PreInitializeContext) -> None:
-        catalog = await context.container.get(SettingCatalog)
-        refresh = await context.container.get(SettingsRefreshRuntime)
-        for definition in catalog.handlers:
-            handler = await context.container.get(definition.handler_type)
-            refresh._register(definition.setting, handler)
-        # Manager 固定归 APP；查询最终原生图，含 alias，不构造服务或维护第二清单。
-        # 无存储仍应用只读值；已注册服务由原生 get 解析，构造失败不能降级。
-        if (
-            context.container.registry.get_factory(DependencyKey(SettingManager, DEFAULT_COMPONENT))
-            is not None
-        ):
-            settings = await context.container.get(SettingManager)
-            settings._refresh = refresh
-            self._manager = settings
-
-    async def shutdown(self, context: ShutdownContext) -> None:
-        # 只解除本实例完成的接线；启动部分失败后的关闭不得重新构造依赖。
-        if self._manager is not None:
-            self._manager._refresh = None
-            self._manager = None