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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (93) hide show
  1. python_ddd_framework/__init__.py +17 -1
  2. python_ddd_framework/application/builder.py +38 -32
  3. python_ddd_framework/application/runtime_hooks.py +5 -3
  4. python_ddd_framework/application/state.py +2 -0
  5. python_ddd_framework/auditing/sqlalchemy/mappings.py +29 -0
  6. python_ddd_framework/auditing/sqlalchemy/module.py +1 -2
  7. python_ddd_framework/auditing/sqlalchemy/store.py +23 -15
  8. python_ddd_framework/caching/unit_of_work.py +4 -0
  9. python_ddd_framework/consumer_docs/README.md +91 -0
  10. python_ddd_framework/consumer_docs/architecture.md +264 -0
  11. python_ddd_framework/consumer_docs/development.md +934 -0
  12. python_ddd_framework/developer_kit/templates/basic/{{cookiecutter.module_name}}/README.md +13 -1
  13. python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/README.md +18 -29
  14. python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/module.py.jinja +2 -4
  15. python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/AGENTS.md +33 -54
  16. python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/README.md +32 -19
  17. python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/backend/pyproject.toml.jinja +15 -1
  18. python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/architecture.md +22 -151
  19. python_ddd_framework/developer_kit/templates/project/{{cookiecutter.project_name}}/docs/development.md +38 -541
  20. python_ddd_framework/domain/__init__.py +5 -0
  21. python_ddd_framework/domain/aggregates.py +5 -35
  22. python_ddd_framework/domain/auditing.py +11 -0
  23. python_ddd_framework/domain/capabilities.py +39 -0
  24. python_ddd_framework/domain/entities.py +0 -2
  25. python_ddd_framework/entity_caching/__init__.py +5 -0
  26. python_ddd_framework/entity_caching/cache.py +95 -0
  27. python_ddd_framework/entity_caching/contracts.py +22 -0
  28. python_ddd_framework/entity_caching/module.py +9 -0
  29. python_ddd_framework/entity_caching/registration.py +131 -0
  30. python_ddd_framework/events/aggregate.py +6 -13
  31. python_ddd_framework/events/runtime.py +93 -27
  32. python_ddd_framework/extensions/__init__.py +2 -0
  33. python_ddd_framework/extensions/catalog.py +4 -0
  34. python_ddd_framework/extensions/contracts.py +12 -2
  35. python_ddd_framework/identity/application.py +2 -4
  36. python_ddd_framework/identity/domain_rules.py +4 -2
  37. python_ddd_framework/identity/dtos.py +19 -20
  38. python_ddd_framework/identity/management.py +14 -11
  39. python_ddd_framework/identity/models.py +28 -36
  40. python_ddd_framework/identity/seeding.py +2 -2
  41. python_ddd_framework/identity/sqlalchemy/mappings.py +132 -0
  42. python_ddd_framework/identity/sqlalchemy/module.py +1 -11
  43. python_ddd_framework/identity/sqlalchemy/repository.py +147 -178
  44. python_ddd_framework/identity/sqlalchemy/session_security.py +8 -9
  45. python_ddd_framework/identity/sqlalchemy/stores.py +110 -86
  46. python_ddd_framework/identity/stores.py +5 -5
  47. python_ddd_framework/invocation/runtime.py +6 -0
  48. python_ddd_framework/services/__init__.py +2 -1
  49. python_ddd_framework/services/composition.py +8 -0
  50. python_ddd_framework/services/convention.py +28 -1
  51. python_ddd_framework/services/repository.py +31 -29
  52. python_ddd_framework/services/runtime.py +4 -0
  53. python_ddd_framework/settings/sqlalchemy/mappings.py +31 -0
  54. python_ddd_framework/settings/sqlalchemy/module.py +1 -2
  55. python_ddd_framework/settings/sqlalchemy/store.py +66 -45
  56. python_ddd_framework/sqlalchemy/__init__.py +8 -6
  57. python_ddd_framework/sqlalchemy/alembic_runtime/env.py +3 -0
  58. python_ddd_framework/sqlalchemy/auditing.py +112 -30
  59. python_ddd_framework/sqlalchemy/conventions.py +54 -0
  60. python_ddd_framework/sqlalchemy/event_origins.py +163 -0
  61. python_ddd_framework/sqlalchemy/extensions.py +81 -49
  62. python_ddd_framework/sqlalchemy/locking.py +22 -0
  63. python_ddd_framework/sqlalchemy/mapping.py +53 -0
  64. python_ddd_framework/sqlalchemy/metadata.py +27 -47
  65. python_ddd_framework/sqlalchemy/metadata_builder.py +26 -20
  66. python_ddd_framework/sqlalchemy/metadata_fingerprint.py +4 -1
  67. python_ddd_framework/sqlalchemy/metadata_ownership.py +1 -1
  68. python_ddd_framework/sqlalchemy/migration.py +3 -5
  69. python_ddd_framework/sqlalchemy/migration_rendering.py +25 -0
  70. python_ddd_framework/sqlalchemy/module.py +56 -3
  71. python_ddd_framework/sqlalchemy/module_migration.py +4 -4
  72. python_ddd_framework/sqlalchemy/repository.py +139 -64
  73. python_ddd_framework/sqlalchemy/repository_binding.py +152 -0
  74. python_ddd_framework/sqlalchemy/session_provider.py +16 -21
  75. python_ddd_framework/sqlalchemy/tracking.py +231 -0
  76. python_ddd_framework/sqlalchemy/types.py +25 -0
  77. python_ddd_framework/sqlalchemy/unit_of_work.py +110 -6
  78. python_ddd_framework/unit_of_work/contracts.py +13 -6
  79. python_ddd_framework/unit_of_work/lifecycle.py +3 -0
  80. python_ddd_framework/unit_of_work/manager.py +17 -4
  81. python_ddd_framework-0.10.1.dist-info/METADATA +363 -0
  82. {python_ddd_framework-0.9.0.dist-info → python_ddd_framework-0.10.1.dist-info}/RECORD +87 -70
  83. {python_ddd_framework-0.9.0.dist-info → python_ddd_framework-0.10.1.dist-info}/WHEEL +1 -1
  84. python_ddd_framework-0.10.1.dist-info/licenses/LICENSE +21 -0
  85. python_ddd_framework/auditing/sqlalchemy/models.py +0 -31
  86. python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/models/base.py.jinja +0 -7
  87. python_ddd_framework/identity/sqlalchemy/models.py +0 -104
  88. python_ddd_framework/settings/sqlalchemy/models.py +0 -36
  89. python_ddd_framework-0.9.0.dist-info/METADATA +0 -619
  90. python_ddd_framework-0.9.0.dist-info/licenses/LICENSE +0 -7
  91. /python_ddd_framework/developer_kit/templates/module/{{cookiecutter.module_name}}/sqlalchemy/{models → mappings}/__init__.py.jinja +0 -0
  92. {python_ddd_framework-0.9.0.dist-info → python_ddd_framework-0.10.1.dist-info}/entry_points.txt +0 -0
  93. {python_ddd_framework-0.9.0.dist-info → python_ddd_framework-0.10.1.dist-info}/licenses/src/python_ddd_framework/background_jobs/pgqueuer/UPSTREAM_LICENSE.txt +0 -0
@@ -11,6 +11,8 @@ This basic module demonstrates an ordinary in-process DI service. Text conversio
11
11
 
12
12
  The CLI adds `{{ cookiecutter.class_prefix }}Module` to the Host dependencies and publishes the `{{ cookiecutter.module_name }}` alias through the project's standard module entry points. This template does not require database or Redis providers. Other modules selected by your Host may require them.
13
13
 
14
+ <a id="consume-the-interface"></a>
15
+
14
16
  ## Consume the interface
15
17
 
16
18
  Declare a dependency on `{{ cookiecutter.class_prefix }}Module` in the consuming Module and inject `ConversionService` through a constructor. Keep the consuming service in that Module's `scan_packages`:
@@ -34,6 +36,8 @@ class LabelsModule(AppModule):
34
36
 
35
37
  Add `LabelsModule` to the Host dependencies. Each resolution inside a REQUEST creates a fresh transient instance; dependencies still obey their own scope constraints. No custom Provider, factory, or service locator is required.
36
38
 
39
+ <a id="lifecycle-and-replacement"></a>
40
+
37
41
  ## Lifecycle and replacement
38
42
 
39
43
  All seven lifecycle hooks are explicit. Empty hooks use `pass`; composition is synchronous and does not start I/O, while initialization and shutdown are asynchronous. Resources belong to the Module that creates them and must be released before shutdown returns.
@@ -42,4 +46,12 @@ To replace the example, subclass `DefaultConversionService` in a consuming Modul
42
46
 
43
47
  The synchronous `to_upper` method is unmarked and returns `text.upper()`. It is not an ApplicationService, has no interception or HTTP exposure, and does not open a transaction. To use authorization, validation, or UoW interception later, adopt the supported asynchronous instance-method contract and explicitly declare its capability dependencies and policies.
44
48
 
45
- This template generates no Domain, persistence, migration, seed, HTTP, background task, or empty layer. Use `pddd add module <name> --template ddd` for the complete six-layer example instead. Project commands can run from the application root or any child directory; Python files and metadata belong under `backend/`.
49
+ This template generates no Domain, persistence, migration, seed, HTTP, background task, or empty layer. Use `pddd add module <name> --template ddd` for the complete six-layer skeleton instead. Installed `pddd` commands can run from the application root or any child directory; run native uv/build/test and Docker/Compose commands from `backend/`, which owns Python files and metadata.
50
+
51
+ <a id="framework-reference-and-module-decisions"></a>
52
+
53
+ ## Framework reference and module decisions
54
+
55
+ Use [Framework documentation](../../../../docs/development.md#framework-documentation) to locate `python_ddd_framework/consumer_docs/README.md#capabilities`, `python_ddd_framework/consumer_docs/development.md#dependency-injection`, and `python_ddd_framework/consumer_docs/architecture.md#calls-scopes-and-transactions`. Read both contract and usage before changing registration, lifetime or policies.
56
+
57
+ Record this module's confirmed responsibility, callers, public contract, actual framework choices and verification here. The initial conversion example above describes the generated code; it does not authorize unrelated business rules. Keep generic framework instructions in the installed guide. This README belongs to the application and is not overwritten by upgrades.
@@ -2,7 +2,9 @@
2
2
 
3
3
  This is a DDD module skeleton. It has no business rules, entities, DTOs, services, endpoints, database tables, seed data, background tasks, or test cases. The Host selects its Application, SQLAlchemy, and HttpApi Modules; infrastructure providers remain Host-owned.
4
4
 
5
- [Project setup](../../../../README.md) · [Working rules](../../../../AGENTS.md) · [Architecture](../../../../docs/architecture.md) · [Design checks](../../../../docs/development.md#design-and-delivery-checks) · [Directory rules](../../../../docs/development.md#module-layout-and-coding-rules)
5
+ [Project setup](../../../../README.md) · [Working rules](../../../../AGENTS.md) · [Architecture](../../../../docs/architecture.md) · [Design checks](../../../../docs/development.md#framework-documentation) · [Directory rules](../../../../docs/development.md#framework-documentation)
6
+
7
+ <a id="record-the-business-responsibility"></a>
6
8
 
7
9
  ## Record the business responsibility
8
10
 
@@ -10,6 +12,8 @@ Before implementation, record the confirmed capability, caller, business languag
10
12
 
11
13
  Keep this README current with the implementation and its actual verification. A small correction may reference existing conclusions rather than creating another design document.
12
14
 
15
+ <a id="layers-and-initial-wiring"></a>
16
+
13
17
  ## Layers and initial wiring
14
18
 
15
19
  | Layer | Responsibility and current state |
@@ -18,42 +22,27 @@ Keep this README current with the implementation and its actual verification. A
18
22
  | `domain` | Aggregates, domain services, repository contracts, events, settings, and seed contributors. Depends on DomainShared; it contains no business implementation. |
19
23
  | `application_contracts` | Public service Protocols and input/output DTOs. Depends on DomainShared; contracts do not depend on Domain or implementations. |
20
24
  | `application` | Use-case orchestration and handlers. Depends on Domain and ApplicationContracts; its package is scanned but has no services or task declarations. |
21
- | `sqlalchemy` | Persistence implementations and owned migrations. Depends on Domain and SqlAlchemyPersistenceModule; it retains its Base, model discovery, repository scanning, and migration registration. |
25
+ | `sqlalchemy` | Persistence implementations and owned migrations. Depends on Domain and SqlAlchemyPersistenceModule; it retains native mapping discovery, repository scanning, and migration registration. |
22
26
  | `http_api` | Transport declarations. Depends on FastApiModule and exposes this module's contracts; empty contracts produce no business endpoints. |
23
27
 
24
28
  All responsibility directories and package markers are retained for navigation. Add implementations only for authorized requirements; do not fill them with placeholder interfaces or services. `module.py` owns dependencies, registration, and the seven lifecycle hooks. Empty hooks use `pass`; package markers contain no business or compatibility exports. `tests/` initially contains only its package marker.
25
29
 
26
- ## Implement the first use case
27
-
28
- 1. Identify **owner -> layer -> directory -> verified framework API**, following the project design checks. Add shared values only when they are actually shared.
29
- 2. Model aggregate transitions and invariants in Domain. Define domain-facing repositories without ORM or Session types. Add public DTOs and service Protocols in ApplicationContracts, then implement the authorized use case in Application.
30
- 3. Declare the framework capability dependencies where used: for example, ApplicationServicesModule for application services, AuthorizationModule for permission definitions, or DataSeedingModule for seed contributors. The Host's provider choices do not repair missing module dependencies.
31
- 4. Implement persistence under `sqlalchemy/models` and `sqlalchemy/repositories`. The existing [Base](sqlalchemy/models/base.py) and [registration](sqlalchemy/module.py) own this module's metadata and migration branch. Business models, tables, and schema decisions must come from requirements.
32
- 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.
33
- 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.
34
-
35
- ## Global settings
36
-
37
- 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.
38
-
39
- 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.
30
+ <a id="framework-reference-and-first-use-case"></a>
40
31
 
41
- ## Persistence and verification
32
+ ## Framework reference and first use case
42
33
 
43
- 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:
34
+ Use [Framework documentation](../../../../docs/development.md#framework-documentation) to locate these installed-package resources:
44
35
 
45
- ```sh
46
- pddd db revision --module {{ cookiecutter.module_name }}
47
- pddd db upgrade --module {{ cookiecutter.module_name }}
48
- pddd db status --module {{ cookiecutter.module_name }}
49
- ```
36
+ - `python_ddd_framework/consumer_docs/README.md#capabilities` — choose only the capabilities required by confirmed business behavior.
37
+ - `python_ddd_framework/consumer_docs/development.md#implementation-workflow` — owner, layer, directory, public API and verification.
38
+ - `python_ddd_framework/consumer_docs/development.md#module-layout-and-coding-rules` — complete responsibility directories.
39
+ - `python_ddd_framework/consumer_docs/architecture.md#business-module-boundaries` — contract and data boundaries.
40
+ - `python_ddd_framework/consumer_docs/development.md#persistence-and-migrations` — mappings, repositories and owned revisions when persistence is required.
50
41
 
51
- Run `pddd db seed --module {{ cookiecutter.module_name }}` only after declaring the intended contributors and preparing their database. Keep applied revisions immutable and upgrade prerequisites explicitly. Host startup never migrates or seeds.
42
+ For each chosen capability, read both its contract and usage from the capability index. Declare the actual Module dependencies; Host provider choices do not repair missing business-module dependencies. The existing [persistence registration](sqlalchemy/module.py) owns this module's mapping discovery and migration branch. Implement only the authorized use case, then record its actual API, dependencies/provider needs, business invariants and verification here. Do not duplicate the full framework guide.
52
43
 
53
- Run installed `pddd` commands from any application directory. Run native tools from `backend/`:
44
+ <a id="verification-and-decisions"></a>
54
45
 
55
- ```sh
56
- uv build --no-sources
57
- ```
46
+ ## Verification and decisions
58
47
 
59
- After authorized test cases exist, run `uv run pytest src/modules/{{ cookiecutter.module_name }}/tests`. The empty skeleton has no tests to pass. Host tests cover generic health and identity and require their configured infrastructure; see the project verification guide. Module tests are excluded from production wheels and service discovery. The `basic` template remains available for an ordinary in-process service without DDD layers.
48
+ This skeleton has no test cases or business tables. Composition, an empty test directory or a zero-test run is not business evidence. Select the smallest relevant existing checks; new tests and real-infrastructure validation need task authorization. Record confirmed decisions, concrete rejection examples, actual results and open questions as implementation proceeds. Framework upgrades do not overwrite this README.
@@ -1,7 +1,6 @@
1
1
  """provider 依赖领域契约;Host 显式选择此实现。"""
2
2
 
3
3
  from modules.{{ cookiecutter.module_name }}.domain.module import {{ cookiecutter.class_prefix }}DomainModule
4
- from modules.{{ cookiecutter.module_name }}.sqlalchemy.models.base import {{ cookiecutter.class_prefix }}Base
5
4
 
6
5
  from python_ddd_framework import (
7
6
  AppModule,
@@ -21,9 +20,8 @@ from python_ddd_framework.sqlalchemy import (
21
20
 
22
21
 
23
22
  @contributes_sqlalchemy_models(
24
- SqlAlchemyModelRegistration.from_package(
25
- models_package=__package__ + ".models",
26
- metadata={{ cookiecutter.class_prefix }}Base.metadata,
23
+ SqlAlchemyModelRegistration(
24
+ mappings_package=__package__ + ".mappings",
27
25
  migrations_package=__package__ + ".migrations",
28
26
  branch_label="{{ cookiecutter.module_name }}",
29
27
  )
@@ -1,74 +1,53 @@
1
1
  # Project development guidance
2
2
 
3
- These instructions apply to this application and its business modules. Follow the user's task scope and any more specific instructions in the affected directory.
3
+ <a id="framework-reference"></a>
4
4
 
5
- ## Start with the affected capability
5
+ ## Framework reference
6
6
 
7
- 1. Check the branch, worktree, requested outcome, and existing changes before editing. Analysis and review requests are read-only unless implementation is requested.
8
- 2. Read the applicable project requirements and accepted decisions, then [architecture](docs/architecture.md) for ownership and dependencies and the relevant section of [development](docs/development.md) for framework usage. Use [README](README.md) for setup and operations. This reading order is required before implementation; reuse existing conclusions for a small change.
9
- 3. Before changing a business module, read its `backend/src/modules/<name>/README.md`, then inspect the affected source and direct callers. Use the workflow below to choose the layer and responsibility directory. Expand the investigation only when those facts reveal another affected boundary.
10
- 4. Read versions and dependencies from `backend/pyproject.toml` and exact resolutions from `backend/uv.lock`. Follow [installed framework lookup](docs/development.md#match-the-installed-framework) for the actual package, bundled examples, CLI, and any user-provided source reference. Check the consumed artifact before relying on a checkout; equal version numbers do not prove identical contents. Generated guidance records the template version; upgrades do not update it automatically.
7
+ Framework distribution: `python-ddd-framework`.
8
+ Python package: `python_ddd_framework`.
11
9
 
12
- Python code, metadata, configuration, environment, and deployment files belong under `backend/`. Root `scripts/` contains consumer-owned scripts. Run installed `pddd` commands from any directory in the application; run native uv/build/test and Docker commands from `backend/`.
10
+ Use [Framework documentation](docs/development.md#framework-documentation)
11
+ to locate the framework installed in this project's backend environment.
13
12
 
14
- Use the [official CLI entry points](docs/development.md#cli-operations) for operations it provides, including project/module generation, development startup, infrastructure preparation, migrations, seeding, and inspection. Do not replace them with handwritten generation or direct calls to migration/seed internals. Build and test still use native tools.
13
+ Framework resources:
15
14
 
16
- ## Work from business rules to framework code
15
+ - `python_ddd_framework/consumer_docs/README.md#capabilities` — capability discovery.
16
+ - `python_ddd_framework/consumer_docs/development.md#implementation-workflow` — development workflow and usage.
17
+ - `python_ddd_framework/consumer_docs/architecture.md#ownership-and-dependencies` — public contracts and ownership boundaries.
17
18
 
18
- 1. Describe the requested use case in business terms: caller, command or query, expected outcome, allowed state changes, and failure conditions. Reuse the module's recorded language and rules. The DDD skeleton supplies structure without business rules; documentation recipes are illustrations, and actual requirements come from the application.
19
- 2. For a domain change, identify the rule owner, aggregate boundary, consistency needs, and collaboration with other modules using [business-change planning](docs/development.md#plan-a-business-change). Keep confirmed decisions in the owning module README. Ask about missing rules that affect correctness; label proposals and open questions instead of presenting assumptions as approved rules.
20
- 3. Before the first edit, identify **Owner -> layer -> target directory -> verified framework API**, with the relevant requirement and source/example evidence, using the [design and delivery checks](docs/development.md#design-and-delivery-checks). Choose the existing `basic` or `ddd` layout using the [directory rules](docs/development.md#module-layout-and-coding-rules), then map needed capabilities through the [framework selection table](docs/development.md#choose-a-framework-capability). Check the installed API, Module declarations, and existing usage before implementing. Mark an API check as not applicable when appropriate; do not invent an abstraction to fill the record.
21
- 4. Implement the authorized use case through its public contract, domain behavior, and existing persistence/invocation boundaries. Reuse existing validation and [verification commands](docs/development.md#verification); state which domain rules, composition paths, and infrastructure behavior the checks actually cover. Scale this process to the change: a local correction can reuse the existing model directly.
19
+ These are installed-package resource paths, not paths relative to this project's root.
20
+ Read the capability index and the chapters relevant to the requested behavior before implementation; verify activation requirements and the existing public API. If a capability appears insufficient, identify the exact missing behavior and the installed API/extension point checked before proposing another mechanism. Do not infer absence from a missing document or invent business requirements from examples.
22
21
 
23
- ## Preserve ownership and contracts
22
+ <a id="project-working-rules"></a>
24
23
 
25
- - The Host composes modules, selects providers, and supplies configuration. Keep business state and rules in their owning modules.
26
- - 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.
27
- - 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.
28
- - 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.
29
- - 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.
30
- - If requirements, accepted decisions, documented responsibilities/contracts, an approved plan, or implementation conflict, pause affected edits and commits. Present both statements with file locations, current behavior, impact, and the decision needed from the user. Obtain an explicit ruling before proceeding; silence or a general instruction to continue does not resolve an unstated boundary change. Never rewrite documentation to retroactively authorize an incorrect implementation.
31
- - Confirm changes to dependencies, public contracts, persistent data, external protocols, or deployment infrastructure when they extend beyond the requested task. Internal simplification does not authorize breaking consumers or stored data.
24
+ ## Project working rules
32
25
 
33
- Use the documented responsibility directories for every new capability. Propose a standards change before adding a responsibility category or changing dependency direction. The `ddd` template intentionally retains the full responsibility directories, package markers, Module hooks, ORM Base, and model/migration registration. It generates no business implementations or test cases; this directory exception applies to DDD templates and generated projects, not speculative framework runtime layers. The `basic` template generates only package markers, `module.py`, `contracts/conversion_service.py`, `services/default_conversion_service.py`, and its README. It uses ordinary transient DI, without Domain, persistence, HTTP, interception, or empty layers. Keep `module.py` limited to dependencies, registration, and lifecycle hooks, and keep package `__init__.py` free of business code and compatibility exports.
26
+ These instructions apply to this application and its modules. Follow the user's task scope and more specific applicable project instructions. This file is application-owned after generation; framework upgrades do not overwrite it.
34
27
 
35
- ## Enforce DDD rules
28
+ 1. Check the branch, worktree, requested outcome and existing changes. Analysis and review are read-only unless implementation is requested.
29
+ 2. Read confirmed requirements, accepted project decisions, [project architecture](docs/architecture.md), [development](docs/development.md), and the affected `backend/src/modules/<name>/README.md`. Use [README](README.md) for setup and operations.
30
+ 3. Follow the installed framework's implementation workflow. Before editing, identify **owner -> layer -> directory -> verified framework API**, including Module/provider activation. Reuse existing conclusions for a small correction; do not create a design file just to satisfy a checklist.
31
+ 4. Resolve a conflict between requirements, contracts, decisions or implementation before affected changes. Present both statements and their locations; do not rewrite rules to justify an implementation. Silence or a generic instruction to continue does not decide an unstated contract change.
32
+ 5. Use existing framework capabilities and native extension points first. New dependencies, copied third-party code, tests, public contracts, persistent-data changes or infrastructure require authorization when outside the confirmed task.
33
+ 6. Review ownership, dependency direction, business invariants, errors, concurrency, cancellation and cleanup on the final diff. Passing unrelated tests does not prove these properties. Report the selected capability, actual verification and remaining limits.
36
34
 
37
- For a modeled domain capability, apply the [mandatory DDD rules](docs/architecture.md#mandatory-ddd-rules) during implementation and review. Reject application code that assigns aggregate business state directly, writes aggregate children outside the root's business operations, or leaks ORM/Session types through domain repository contracts. Before a cross-aggregate write, record its consistency, failure, and idempotency decisions. Keep each changed invariant's owner, operation, and rejection example in the module README and verify them with the [business-change checks](docs/development.md#check-a-domain-change). These rules do not require a `basic` service to acquire unused DDD layers.
35
+ Python code, metadata, configuration and deployment files belong under `backend/`; root `scripts/` belongs to the application. Use installed `pddd` for its official operations; run native uv/build/test and Docker commands from `backend/`. The framework's installed files and a supplied framework checkout are read-only references, not application-edit destinations.
38
36
 
39
- Code and architecture changes must also satisfy the [seven design principles](docs/architecture.md#mandatory-design-principles). Review the applicable principles, DDD boundaries, imports, contracts, state ownership, and resource lifetimes on the final diff. Follow the [delivery checks](docs/development.md#design-and-delivery-checks) and cite actual evidence. Correct confirmed violations within the authorized scope or report the blocking decision; passing builds/tests alone cannot justify completion. These requirements do not authorize new business rules, dependencies, tests, automated gates, infrastructure, or framework changes.
37
+ <a id="verify-and-maintain"></a>
40
38
 
41
- ## Use the framework safely
42
-
43
- - Extend only explicitly opened targets. Keep typed properties in application contracts, optional SQL mappings and local extension revisions in persistence, and reuse the same declaration for validation, OpenAPI, and storage. Never mutate shared DTO/ORM classes or duplicate the base table/Schema owner; extension migrations declare Alembic prerequisites explicitly.
39
+ ## Verify and maintain
44
40
 
45
- - Invoke application services through their injected public contracts or the framework functions `invoke(application, ...)` / `call(application, ...)`. Manual construction and self-calls do not create a new managed invocation.
46
- - Ordinary DI services opt into interception with `@unit_of_work`, `@authorize`, or `ValidationEnabled`; declare the corresponding capability dependency on their owning Module. Keep marked methods async instance methods and preserve native scope/cache. These declarations do not add HTTP exposure or require ApplicationService inheritance.
47
- - Keep transactions short. Never carry a business Session or UoW across a network wait or stream `yield`, or transfer execution scopes into ordinary child tasks or external threads. Managed HTTP streaming retains only its transport-owned REQUEST until cleanup; follow the [streaming boundaries](docs/architecture.md#http-streaming-and-continuous-access) and [complete example](docs/development.md#http-generators-and-continuous-access).
48
- - Keep aggregate rules and optimistic concurrency checks intact. Construct aggregate events from frozen records and stable nested values as described in [architecture](docs/architecture.md#calls-scopes-and-transactions). Use repository operations to stage changes and collect events; do not publish the same aggregate events twice.
49
- - Review generated migrations. Do not edit applied revisions, bypass migration guards, or treat Host startup as migration or seeding.
50
- - Keep background side effects idempotent. Local events and WebSocket messages do not provide durable distributed delivery; distributed locks do not replace database concurrency or idempotency.
51
- - Validate external inputs, propagate meaningful failures, and preserve cancellation and cleanup. Add defaults, retries, or fallbacks only for an identified requirement.
52
- - Use typed public APIs and native framework extension points. Keep dynamic data narrowing at external boundaries; do not use `Any`, unchecked casts, or broad exception handlers to hide contract mistakes.
53
- - Keep Job identity in its definition and realtime names/schemas in typed message classes under `domain_shared/messages`; callers provide typed values. Explicit public error data belongs to a Pydantic DTO selected by the business. Preserve existing wire names and fields when changing these schemas; queue acceptance is not delivery acknowledgment.
41
+ - Preserve unrelated changes. Use the smallest relevant existing checks and authorized build. Do not add test files/cases/dependencies without approval; do not run infrastructure or long tests without the task's authorization.
42
+ - Record actual commands and results. Distinguish static checks, behavior tests, real infrastructure and independent distribution validation; do not treat skips or unexecuted checks as success.
43
+ - Update module README for business rules, public behavior and capability choices; architecture for project boundaries; development for local procedures; README for operations. Keep framework rules in the installed guides and project facts here.
44
+ - Use the existing directory conventions and keep DDD skeletons free of invented business code. Propose a rules change before adding a new responsibility category or dependency direction.
45
+ - Do not commit, push or delete retained temporary evidence unless explicitly requested. Framework upgrades update package resources, not these project files.
54
46
 
55
- For in-process messages, read the [message example](docs/development.md#in-process-messages).
56
- Business modules own message values and coalescing identities. Only replaceable snapshots may
57
- coalesce. Acceptance, processing, commit and external acknowledgement are separate facts.
58
- Use the framework channel and hosted bridge; preserve capacity and actual cleanup guarantees.
47
+ <a id="project-specific-decisions"></a>
59
48
 
60
- For SDK shutdown, initiate business cleanup in `HostedService.stopping(context, reason)` and
61
- release resources in `stop(reason)`. Pass the separate stopping context only to this phase's
62
- callbacks; startup contexts never gain shutdown permissions. Channels opt in with declared
63
- `stopping_owners` and `send/submit(..., stopping=context)`. Keep the channel Module dependent on
64
- the service owner, and drain accepted work before releasing resources. See the hosted-service
65
- and message examples in the project development guide.
49
+ ## Project-specific decisions
66
50
 
67
- ## Verify and maintain
51
+ Record only confirmed local conventions and decisions here as the application evolves. Keep the framework reference above usable; it is a normal editable project instruction, not a reserved region or an automatic synchronization marker.
68
52
 
69
- - Preserve unrelated changes. Do not edit the installed framework, generated dependency files by hand, or another repository to make an application change pass.
70
- - Use the smallest relevant existing checks and authorized build. New test files, cases, or test dependencies require explicit approval; explain their scope and verification benefit first. Read fixtures before running infrastructure tests and keep them within the task's authorization. See [verification](docs/development.md#verification) for available commands.
71
- - Distinguish source checks, unit tests, real infrastructure tests, and distribution validation. Report actual results and anything not verified; never claim success from a mock or an unexecuted command.
72
- - Update the owning module README when business rules or public behavior change. Update architecture for dependency or ownership changes, development for usage changes, and README for setup or operations changes. Replace outdated statements rather than appending a work log.
73
- - Documentation guides development; it is not an executable architecture gate. Use type checks and appropriate boundary tests when the project has them.
74
- - Commit or push only when requested. Review the final diff, choose owned paths explicitly, and exclude secrets, caches, temporary artifacts, and unrelated changes.
53
+ For a complete runnable reference, follow `python_ddd_framework/consumer_docs/README.md#demo` in this application's installed environment. Retrieve that exact version's public PyPI sdist and use its Framework Demo README for startup and tests; no private repository access is needed. The Demo is separate from generated scaffolding. Framework unit, CLI/delivery and Demo integration checks prove different boundaries; retain their actual evidence separately. Do not copy framework guidance or Demo business rules into this project without a confirmed requirement. The framework's MIT template license does not decide this application's business-code license.
@@ -1,21 +1,25 @@
1
1
  # {{ cookiecutter.project_name }}
2
2
 
3
- A modular Python application generated with Python DDD Framework {{ cookiecutter.framework_version }}. The initial project contains a Host; add business modules with `pddd add module` and implement their business behavior from confirmed requirements.
3
+ A modular Python application using Python DDD Framework. Resolve the installed framework version through the [project lookup procedure](docs/development.md#framework-documentation). The initial project contains a Host; add business modules with `pddd add module` and implement their business behavior from confirmed requirements.
4
4
 
5
5
  | Document | Purpose |
6
6
  | --- | --- |
7
- | [AGENTS.md](AGENTS.md) | Mandatory reading, implementation, and delivery checks for Codex and other contributors. |
8
- | [Architecture](docs/architecture.md) | Design principles, DDD ownership, dependency direction, transactions, streaming, and lifecycle boundaries. |
9
- | [Development guide](docs/development.md) | CLI entry points, artifact/source lookup, design checks, and framework usage recipes. |
7
+ | [AGENTS.md](AGENTS.md) | Mandatory framework lookup, project instructions, and delivery checks. |
8
+ | [Architecture](docs/architecture.md) | Actual application boundaries, initial Host composition, and confirmed project decisions. |
9
+ | [Development guide](docs/development.md) | Isolated framework-document lookup, local development procedures, and verification. |
10
10
 
11
11
  Each generated business module also has its own README under `backend/src/modules/<name>/`. This README owns application setup and operations.
12
12
 
13
+ <a id="prerequisites"></a>
14
+
13
15
  ## Prerequisites
14
16
 
15
- Python metadata, `.python-version`, `uv.lock`, `.venv`, source, tests, YAML, Compose files, and the Dockerfile belong in `backend/`. Root `scripts/` belongs to application-owned development scripts. Use uv and the Python version declared under `backend/`; Docker with Compose is required for the generated Host's providers. Normal creation synchronizes dependencies. With `pddd new <name> --python <major.minor[.patch]> --no-sync`, creation writes files only, even if that interpreter is absent. Run `uv sync --project backend` afterwards; uv selects or downloads the requested Python. On later checkouts, use `uv sync --project backend --locked`.
17
+ Python metadata, `.python-version`, `uv.lock`, `.venv`, source, tests, YAML, Compose files, and the Dockerfile belong in `backend/`. Root `scripts/` belongs to application-owned development scripts. Use uv and the Python version declared under `backend/`; Docker with Compose is required for the generated Host's providers. Normal creation synchronizes dependencies. With `pddd new <name> --python <major.minor[.patch]> --no-sync`, creation writes files only, even if that interpreter is absent. Enter `backend/` and run `uv sync` afterwards; uv selects or downloads the requested Python. On later checkouts, run `uv sync --locked` from `backend/`.
16
18
 
17
19
  Run `pddd` project commands from the application root, `backend/`, or any child directory. Host entry points identify the owning backend; unrelated nested Python projects do not redirect the command. The CLI uses that backend's existing environment and framework version. Synchronize explicitly before the first project command. Inside `backend/`, `uv run pddd` is also available; from other locations use the installed `pddd` launcher. Use `pddd` or a subcommand's `--help` to see available commands and options.
18
20
 
21
+ <a id="prepare-local-development"></a>
22
+
19
23
  ## Prepare local development
20
24
 
21
25
  Review `backend/app.development.yaml`, then start the local infrastructure:
@@ -35,6 +39,8 @@ pddd add module conversions --template basic
35
39
 
36
40
  The `orders` name here selects a package, not an order implementation. Read `backend/src/modules/orders/README.md` before adding business code; all responsibility directories are present, but no business service, table, route, or test is generated. The project is also usable as a pure Host without this step.
37
41
 
42
+ <a id="initialize-the-database"></a>
43
+
38
44
  ## Initialize the database
39
45
 
40
46
  Apply the migrations for the providers selected by the generated Host:
@@ -61,11 +67,13 @@ pddd db status --module orders
61
67
  pddd db seed --module orders
62
68
  ```
63
69
 
64
- All database operations select an explicit module. Upgrade prerequisite owners explicitly; commands do not migrate unrelated modules. Host startup does not migrate or seed. Database commands do not start workers or hosted services. See [persistence and migrations](docs/development.md#persistence-and-migrations) before changing models or existing data.
70
+ All database operations select an explicit module. Upgrade prerequisite owners explicitly; commands do not migrate unrelated modules. Host startup does not migrate or seed. Database commands do not start workers or hosted services. See [persistence and migrations](docs/development.md#framework-documentation) before changing models or existing data.
71
+
72
+ <a id="run-and-inspect"></a>
65
73
 
66
74
  ## Run and inspect
67
75
 
68
- To add fields to an explicitly extensible module such as Identity, follow [Extend reusable modules](docs/development.md#extend-reusable-modules). Upgrade the base owner before generating your customer module's extension revision. Keep all new revisions in this project's extension module; framework installation files are not an authoring destination.
76
+ To add fields to an explicitly extensible module such as Identity, follow [Extend reusable modules](docs/development.md#framework-documentation). Upgrade the base owner before generating your customer module's extension revision. Keep all new revisions in this project's extension module; framework installation files are not an authoring destination.
69
77
 
70
78
  ```sh
71
79
  pddd dev
@@ -73,7 +81,7 @@ pddd dev
73
81
 
74
82
  Open **http://127.0.0.1:8000/docs**. Call `/api/auth/login` using the generated `identity.seed_admin_username` and `identity.seed_admin_password` from `backend/app.development.yaml`, then enter the access token in **Authorize**. Local credentials must not be reused for production.
75
83
 
76
- Identity includes paged user/role management, password operations, and version-protected assignments. Before using it, apply the framework's Identity migrations; preserve the returned `concurrency_version` in updates. See [Identity management](docs/development.md#identity-management) for API usage, session invalidation, and Host authorization options.
84
+ Identity includes paged user/role management, password operations, and version-protected assignments. Before using it, apply the framework's Identity migrations; send the returned `version` as `expected_version` in updates. See [Identity management](docs/development.md#framework-documentation) for API usage, session invalidation, and Host authorization options.
77
85
 
78
86
  Adding a DDD skeleton creates no business HTTP endpoints. Implement the public contracts and use cases first, then inspect OpenAPI and update the module README with their actual behavior.
79
87
 
@@ -87,12 +95,16 @@ pddd inspect --environment development
87
95
 
88
96
  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).
89
97
 
98
+ <a id="use-global-settings"></a>
99
+
90
100
  ## Use global settings
91
101
 
92
- 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.
102
+ 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#framework-documentation) for definition discovery, YAML/environment fallback, service injection, and HTTP read/update/reset.
93
103
 
94
104
  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.
95
105
 
106
+ <a id="test-and-package"></a>
107
+
96
108
  ## Test and package
97
109
 
98
110
  ```sh
@@ -101,11 +113,13 @@ uv run pytest
101
113
  uv build --no-sources
102
114
  ```
103
115
 
104
- The application tests include real Host infrastructure and require Docker. A DDD skeleton has no test cases; after authorized domain tests exist, run them separately; see [verification](docs/development.md#verification). Module tests are excluded from production wheels and service discovery.
116
+ The application tests include real Host infrastructure and require Docker. A DDD skeleton has no test cases; after authorized domain tests exist, run them separately; see [verification](docs/development.md#framework-documentation). Module tests are excluded from production wheels and service discovery.
117
+
118
+ <a id="deploy"></a>
105
119
 
106
120
  ## Deploy
107
121
 
108
- Run Docker and Compose commands from `backend/`. The deployment supplies `backend/app.production.yaml`, following the development file's key structure with independent database, Redis, JWT, and administrator credentials. Set the production logging environment and format. Keep the file out of Git and the image; production Compose mounts it read-only at `/app/app.production.yaml` for both web and migration services.
122
+ Run Docker and Compose commands from `backend/`. The deployment supplies `app.production.yaml` in that directory, following the development file's key structure with independent database, Redis, JWT, and administrator credentials. Set the production logging environment and format. Keep the file out of Git and the image; production Compose mounts it read-only at `/app/app.production.yaml` for both web and migration services.
109
123
 
110
124
  Build an image, validate it, and set `APP_IMAGE` to its immutable digest. In PowerShell, run the following for each required module, replacing the module alias and digest:
111
125
 
@@ -126,9 +140,11 @@ The image starts `python -m host.main`, using the public framework server entry
126
140
 
127
141
  The base framework dependency includes runtime capabilities. Production does not require `developer-kit`; generation tools, tests, and development tools are excluded from the final image. Configure TLS, secrets, external health monitoring, capacity, and database recovery for the deployment's actual requirements.
128
142
 
143
+ <a id="upgrade-the-framework"></a>
144
+
129
145
  ## Upgrade the framework
130
146
 
131
- Read the target framework release's migration instructions. Pin `python-ddd-framework` in runtime dependencies and `python-ddd-framework[developer-kit]` in the development group to the same target version. Preserve the application's own dependencies and source overrides.
147
+ Read the target framework artifact's README and capability guides. Pin `python-ddd-framework` in runtime dependencies and `python-ddd-framework[developer-kit]` in the development group to the same target version. Preserve the application's own dependencies and source overrides.
132
148
 
133
149
  For a first move from a local wheel or old Git source to PyPI, remove only the framework entry in `[tool.uv.sources]`; retain other dependencies and vendor files. From the application root, run:
134
150
 
@@ -142,14 +158,11 @@ uv build --no-sources
142
158
 
143
159
  A framework upgrade does not regenerate or overwrite application source, migrations, or these documents. A global CLI upgrade also does not update this project. Apply required adaptations and update the relevant application and module documentation deliberately.
144
160
 
145
- <a id="streaming-and-access-migration-07-unreleased"></a>
146
161
 
147
- ### Streaming and access migration (0.7)
162
+ <a id="framework-reference"></a>
148
163
 
149
- These notes describe the current 0.7.0 implementation; they are not a release announcement. Check the consumed artifact using [installed framework lookup](docs/development.md#match-the-installed-framework) before using these APIs.
164
+ ## Framework reference
150
165
 
151
- - Move `fastapi_realtime.authentication_refresh_seconds` to `fastapi_access.authentication_refresh_seconds` in existing environment files and deployment overrides. Rename `PDDD_FASTAPI_REALTIME__AUTHENTICATION_REFRESH_SECONDS` to `PDDD_FASTAPI_ACCESS__AUTHENTICATION_REFRESH_SECONDS` when set. The old realtime field is rejected. `FastApiAccessOptions` belongs to `FastApiModule` and covers managed HTTP streams and WebSocket connections; its default is 60 seconds and minimum is 1. An omitted section uses these defaults; generation does not need an extra configuration block.
152
- - Existing HTTP streaming code must follow the [preparation, transmission, and cleanup boundaries](docs/architecture.md#http-streaming-and-continuous-access). The [complete generator example](docs/development.md#http-generators-and-continuous-access) demonstrates native SSE, JSONL, and byte streaming. Keep ApplicationService return contracts unchanged and move checks that need ordinary error responses into preparation.
153
- - `run_host(..., timeout_graceful_shutdown=10)` forwards a non-negative integer number of seconds to Uvicorn. At the deadline Uvicorn requests cancellation; framework drain still waits for streams, subscriptions, and REQUEST resources to actually release. This is not a hard process-exit deadline. A synchronous generator's running `next()` must return; its thread is not abandoned. Applications running Uvicorn directly must configure its native timeout themselves.
166
+ Use [Framework documentation](docs/development.md#framework-documentation) to locate the actual installed package. Package-relative resources are `python_ddd_framework/consumer_docs/README.md#capabilities`, `python_ddd_framework/consumer_docs/development.md#cli-operations`, and `python_ddd_framework/consumer_docs/README.md#migration-notes`. Framework rules and recipes stay there; this file owns the application's actual setup and operations. Environment setup above remains usable before the package is installed.
154
167
 
155
- Review applicable [design principles](docs/architecture.md#mandatory-design-principles) and [delivery checks](docs/development.md#design-and-delivery-checks) when adapting existing consumers. Template examples do not authorize application business, schema, dependency, or infrastructure changes.
168
+ For a complete runnable reference, follow `python_ddd_framework/consumer_docs/README.md#demo` in this application's installed environment. Retrieve that exact version's public PyPI sdist and use its Framework Demo README for startup and tests; no private repository access is needed. The Demo is separate from generated scaffolding. Framework unit, CLI/delivery and Demo integration checks prove different boundaries; retain their actual evidence separately. Do not copy framework guidance or Demo business rules into this project without a confirmed requirement. The framework's MIT template license does not decide this application's business-code license.
@@ -8,7 +8,7 @@ dependencies = ["python-ddd-framework=={{ cookiecutter.framework_version }}"]
8
8
  application = "host.main:create_application"
9
9
  web = "host.main:create_web"
10
10
  [dependency-groups]
11
- dev = ["python-ddd-framework[developer-kit]=={{ cookiecutter.framework_version }}", "pytest", "anyio", "testcontainers[postgres,redis]"]
11
+ dev = ["python-ddd-framework[developer-kit]=={{ cookiecutter.framework_version }}", "mypy", "pytest", "anyio", "testcontainers[postgres,redis]"]
12
12
 
13
13
  {% if cookiecutter.framework_source %}[tool.uv.sources]
14
14
  python-ddd-framework = {{ cookiecutter.framework_source }}
@@ -26,3 +26,17 @@ wheel-exclude = ["**/tests/**"]
26
26
  anyio_mode = "auto"
27
27
  testpaths = ["tests", "src/modules"]
28
28
  addopts = "--import-mode=importlib"
29
+
30
+ [tool.mypy]
31
+ files = ["src"]
32
+ strict = true
33
+ plugins = ["pydantic.mypy"]
34
+ disallow_any_unimported = true
35
+ no_implicit_reexport = true
36
+ show_error_codes = true
37
+ warn_unreachable = true
38
+
39
+ [tool.pydantic-mypy]
40
+ init_forbid_extra = true
41
+ init_typed = true
42
+ warn_required_dynamic_aliases = true