python-ddd-framework 0.8.0__tar.gz → 0.9.0__tar.gz

{python_ddd_framework-0.8.0 → python_ddd_framework-0.9.0}/PKG-INFO

@@ -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 → python_ddd_framework-0.9.0}/README.md

@@ -20,7 +20,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. |
@@ -229,6 +229,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/`:
@@ -270,6 +276,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.
@@ -307,7 +323,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 → python_ddd_framework-0.9.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "python-ddd-framework"
-version = "0.8.0"
+version = "0.9.0"
 description = "Modular DDD application framework with project CLI and bundled templates"
 readme = "README.md"
 license = "LicenseRef-Proprietary"

{python_ddd_framework-0.8.0 → python_ddd_framework-0.9.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "python-ddd-framework"
-version = "0.8.0"
+version = "0.9.0"
 description = "Modular DDD application framework with project CLI and bundled templates"
 readme = "README.md"
 license = "LicenseRef-Proprietary"

{python_ddd_framework-0.8.0 → python_ddd_framework-0.9.0}/src/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-0.8.0 → python_ddd_framework-0.9.0}/src/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-0.8.0 → python_ddd_framework-0.9.0}/src/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-0.8.0 → python_ddd_framework-0.9.0}/src/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-0.8.0 → python_ddd_framework-0.9.0}/src/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-0.8.0 → python_ddd_framework-0.9.0}/src/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-0.8.0 → python_ddd_framework-0.9.0}/src/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-0.8.0 → python_ddd_framework-0.9.0}/src/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-0.8.0 → python_ddd_framework-0.9.0}/src/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-0.9.0/src/python_ddd_framework/settings/catalog.py

@@ -0,0 +1,67 @@
+"""Module setting metadata 的 Application-local immutable catalog。"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping
+from types import MappingProxyType
+from typing import Any
+
+from ..diagnostics import SourceLocation
+from ..modularity.discovery import _DiscoveredType
+from .contracts import SettingDefinition
+from .definition_discovery import _collect_setting_definitions
+from .errors import SettingDefinitionError
+
+
+class SettingCatalog:
+    __slots__ = ("_definitions", "_sources")
+
+    def __init__(
+        self,
+        definitions: tuple[SettingDefinition[Any], ...],
+        *,
+        sources: Mapping[str, SourceLocation] | None = None,
+    ) -> None:
+        indexed: dict[str, SettingDefinition[Any]] = {}
+        for definition in definitions:
+            if not isinstance(definition, SettingDefinition):
+                raise SettingDefinitionError(
+                    setting=repr(definition),
+                    reason="catalog entries must be SettingDefinition values",
+                )
+            if definition.name in indexed:
+                raise SettingDefinitionError(
+                    setting=definition.name,
+                    reason="setting is declared more than once",
+                )
+            indexed[definition.name] = definition
+        self._definitions: Mapping[str, SettingDefinition[Any]] = MappingProxyType(
+            dict(sorted(indexed.items()))
+        )
+        self._sources = MappingProxyType(dict(sources or {}))
+
+    @property
+    def sources(self) -> Mapping[str, SourceLocation]:
+        return self._sources
+
+    @property
+    def definitions(self) -> tuple[SettingDefinition[Any], ...]:
+        return tuple(self._definitions.values())
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self._definitions)
+
+    def get(self, name: str) -> SettingDefinition[Any] | None:
+        return self._definitions.get(name)
+
+    def require_owned(self, definition: SettingDefinition[Any]) -> None:
+        if self._definitions.get(definition.name) is not definition:
+            raise SettingDefinitionError(
+                setting=definition.name,
+                reason="definition is not owned by this Application",
+            )
+
+
+def _build_setting_catalog(discoveries: tuple[_DiscoveredType, ...]) -> SettingCatalog:
+    definitions, sources = _collect_setting_definitions(discoveries)
+    return SettingCatalog(definitions, sources=sources)

{python_ddd_framework-0.8.0 → python_ddd_framework-0.9.0}/src/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-0.8.0 → python_ddd_framework-0.9.0}/src/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-0.8.0 → python_ddd_framework-0.9.0}/src/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-0.8.0 → python_ddd_framework-0.9.0}/src/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