Python DDD Framework

Build modular Python applications with explicit domain boundaries, transactional application services, and a consistent path from local development to deployment.

Python DDD Framework combines a module system with FastAPI, Dishka, Pydantic, SQLAlchemy, PostgreSQL, and Redis. It includes the pddd CLI and project templates, so you can create an application, add business modules, manage their database migrations, and run the same application through HTTP, background jobs, or direct service calls.

Python 3.12–3.14 · Windows and Linux · Async application services · Typed public APIs

Features · Quick start · CLI reference · Application development · Deployment · Upgrading · Documentation

Features

The Module owns a feature and its dependencies. The Host composes modules, selects providers, and supplies configuration. Your application owns the generated source code and database migrations.

Runtime integrations ship in the base package; the Host explicitly enables the modules it needs. Installing the package does not start database connections, workers, or trace export. Local events stay within an application process, and WebSocket notifications do not include a distributed backplane or offline replay.

Quick start

Prerequisites

• A supported Python interpreter; the examples use Python 3.12.
• uv for tool installation, dependency management, and project commands.
• Docker with Compose, running locally, for the generated application's PostgreSQL and Redis services.

The supported versions and dependencies are defined in pyproject.toml. The framework, CLI, and bundled templates share one package version.

Version 0.4: This release introduces capability-based composition, current service and Identity APIs, and the backend/ consumer layout with basic/DDD module templates. Existing applications must apply the migration instructions below. Check release status for publication and validation evidence. Use the local-wheel route below when evaluating a checkout that has not been published.

1. Install the CLI and create a project

For a published release:

uv tool install --python 3.12 "python-ddd-framework[developer-kit]"
pddd new my-app --python 3.12
cd my-app

To select a specific release, append ==<version> to the quoted package requirement. pddd new creates the Host, configuration, tests, deployment files, and four application documents: README.md, AGENTS.md, docs/architecture.md, and docs/development.md. Python metadata, configuration, environment, source, tests, and deployment files live in backend/; root scripts/ belongs to the consumer. It then runs uv sync inside backend/ and pins both the runtime dependency and developer tools to the CLI's exact framework version. The destination directory must not already exist. --python accepts a supported portable major.minor[.patch] version. --no-sync writes files only and works without that interpreter installed; later run uv sync --project backend to create the target environment. Native uv/test/build and Docker commands run from backend/.

uv tool install --python 3.12 "<absolute-wheel-path>[developer-kit]"
pddd new my-app --framework-wheel "<absolute-wheel-path>"
cd my-app

2. Prepare infrastructure and add a business module

Run installed pddd project commands from the application root, backend/, or any descendant directory. They locate Host metadata and use the backend's environment and framework version; unrelated nested Python projects do not take ownership:

pddd dev-init
pddd add module orders --template ddd
pddd add module conversions --template basic

dev-init starts or reuses local PostgreSQL and Redis using backend/app.development.yaml. It preserves existing data; database migration and seeding are separate steps.

add module orders generates an order-management example and registers it with the Host. The example includes an aggregate, service contracts, application services, persistence, HTTP endpoints, module tests, and a module README describing its actual behavior and boundaries.

ddd is the default six-layer template. basic generates only a Module, a synchronous Protocol service, its transient implementation, and an English README. It has no database/Redis requirement or implicit HTTP/interception. Both templates support --dry-run and refuse existing targets.

3. Initialize the database

Apply the provider migrations selected by the generated Host, then generate the business module's first migration:

pddd db upgrade --module identity
pddd db upgrade --module settings
pddd db upgrade --module auditing
pddd db upgrade --module background_jobs
pddd db revision --module orders

Review the generated revision in backend/src/modules/orders/sqlalchemy/migrations/ before applying it. Then upgrade and seed:

pddd db upgrade --module orders
pddd db status --module orders
pddd db seed --module identity
pddd db seed --module orders

Migration commands operate on the selected module. When a migration requires another module's revision, upgrade that prerequisite explicitly. Starting the Host does not migrate or seed the database.

4. Run the application and explore the API

pddd dev

Open http://127.0.0.1:8000/docs. Use the generated identity.seed_admin_username and identity.seed_admin_password in backend/app.development.yaml to call /api/auth/login, then enter the returned access token in Swagger's Authorize dialog.

With the orders module installed, you can create and query orders at /api/orders, approve an order at /api/orders/{id}/approve, and enqueue approval at /api/orders/{id}/queue-approval. Swagger shows the request schemas and all available operations. The example also includes file transfer and an authenticated WebSocket endpoint at /ws/orders.

The default business API prefix is /api. Liveness and readiness are exposed at /health/live and /health/ready; readiness describes application lifecycle state, not continuous database or Redis health.

CLI reference

Use pddd to create a project. Inside an existing project, use pddd so commands run with that project's framework version.

Common variations:

pddd new my-app --dry-run
pddd add module billing --dry-run
pddd dev --host 127.0.0.1 --port 8080
pddd inspect --environment development
pddd db status --module orders --environment production

Generation supports --dry-run without writing files. Database commands require --module; aliases come from installed python_ddd_framework.modules entry points and must belong to the current application's module graph.

db and inspect use --environment, then PYTHON_DDD_FRAMEWORK_ENVIRONMENT, then development. dev always selects development, and dev-init is restricted to development infrastructure.

inspect builds and closes the application without starting services or running migrations. Its output describes a newly composed Host, not a running process. Configuration output contains input values and their sources; it does not include Options defaults or later module contributions.

For the complete options supported by your installed version:

pddd
pddd new --help
pddd add module --help
pddd db --help
pddd inspect --help

Application development

Find the right place for a change

The generated project starts with backend/src/host/ for composition and startup. Modules live under backend/src/modules/. A basic module contains module.py, contracts/, services/, and its README. The default ddd module has these responsibilities:

For a new use case, define its input and output in application_contracts/, put business rules in domain/, and coordinate the work in application/. Persist through a repository contract. The HTTP module selects which application services to expose; the Host selects infrastructure providers.

For a model change, edit sqlalchemy/models/, generate a revision, review it, then run db upgrade for that module. For another business module, repeat the add module, db revision, db upgrade, and db seed steps. Add application-specific dependencies with uv add <package>.

See the development guide for service registration, typed invocation, HTTP declarations, transactions, background handlers, and distributed locks.

Configure the application

Edit backend/app.development.yaml for local connections, identity settings, logging, and module Options. An optional backend/app.yaml can hold shared configuration. Environment variables override file inputs; generated Hosts use the PDDD_ prefix and __ between nested fields. For example, PDDD_HTTP__API_PREFIX=/v1 changes the business API prefix.

PYTHON_DDD_FRAMEWORK_ENVIRONMENT selects the Host environment; it is separate from business configuration. Typed Options validate configuration during application composition. Use pddd inspect to investigate input values and where they came from.

Generated credentials are for local development. Production configuration is supplied separately in app.production.yaml. See configuration and background and logging configuration.

Run application tests

After completing local database setup, run from backend/:

uv run pytest

The generated application includes module tests and Host tests. Keep Docker available for tests that use real infrastructure. For custom application tests, the framework's TestApplication reuses the normal application builder and typed service invocation. Framework contributor checks are documented separately in framework validation.

Deployment

Generated applications include backend/Dockerfile and backend/compose.production.yaml. Run build and deployment commands from backend/:

uv build --no-sources

For container deployment:

1. Supply app.production.yaml with production connections and credentials; keep it out of source control and the image. The generated Compose file mounts it read-only for both migration and web services.
2. Build and validate the application image, then set APP_IMAGE to that image's immutable digest.
3. Run database upgrades for each required module in dependency order. Run initial seed operations explicitly with --environment production.
4. Start the web service from the same image and check its health endpoints.

The image uses python -m host.main without development reload. Runtime installations use the base framework package; developer-kit is only needed for generation. Follow the Docker deployment guide for commands and operational boundaries.

Capability module migration (0.4)

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.
• 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.
• HTTP Modules depend on FastApiModule (or FastApiRealtimeModule for its additional capability). The module registers the native FastAPI integration; remove manual FastapiProvider contributions from Host.
• Ordinary DI services can opt into @unit_of_work, @authorize, and ValidationEnabled. Declare their capability dependencies on the service's owning Module and retain the existing native registration. Only marked async instance methods enter interception; class declarations covering synchronous/static/class/generator methods fail at build. Use call / call_as for non-DI callers. These services do not become ApplicationServices or HTTP endpoints.
• Interceptor match functions receive ServiceMethod, replacing ApplicationServiceMethod. Shared method descriptions, validation policies, interception contracts and execution now belong to python_ddd_framework.invocation; import the public symbols from the root package. The old name and moved application_services implementation modules have no forwarding aliases. ApplicationService retains its REQUEST-to-ACTION proxy.

The current contracts are in architecture, the decisions are ADR-015 and ADR-032, and validation limits are in status. Slice 3 data/event migration is documented below; later slice status is recorded on the status page.

Data and event migration (0.4)

• Replace SqlAlchemyRepository.add with insert. Use find for optional results; get now raises ResourceNotFoundError when absent. List/page return lists, insert/update return the entity, and delete/batch methods return None. auto_save=True flushes the owning UoW without committing an outer transaction. Explicit mapping repositories retain their own business methods; update their callers and use the new names where they expose the standard operations.
• Manual UnitOfWorkManager.begin() creates missing execution scopes and owns their exit. Call complete() explicitly. Existing scopes, task/connection limits, outer participation and requires_new ownership remain intact.
• Replace synchronous publish_domain/publish_after_commit with await events.publish(event, phase=LocalEventPhase.DOMAIN/AFTER_COMMIT), or omit phase to notify both. No UoW dispatches immediately; transactional UoW defers by default; nontransactional UoW rejects explicit and automatic events before repository writes. on_unit_of_work_complete=False never advances AFTER_COMMIT ahead of a successful commit.
• Replace CacheDefinition/CacheDefinitions/CacheCatalog with injected DistributedCache[ValueType]; remove cache declarations from Modules. Use @cache_name("stable.name") on the value type if required. Calls take keys/values directly. Configure global caching.default_entry_options or pass a complete DistributedCacheEntryOptions; omitted options use the default 20-minute sliding expiration, while an empty options object is persistent. Development Hosts explicitly set caching.hide_errors: false.
• Redis cache keys and entry encoding changed; old disposable entries are not read or migrated. They expire under their old TTL. consider_uow=True stages writes/deletions per concrete UoW; completion failures retain the committed database fact and do not make the two resources atomic. Do not retry an entire committed business operation merely because an AFTER_COMMIT handler or cache write failed.

Message processing (0.4)

Opt in with MessagingModule, MessageChannelDefinition[T], MessageHandler[T] and the APP-scoped MessageChannel[T]. Register a concrete Handler as a cached ACTION single binding. send() returns an acceptance receipt; receipt.wait() reports processing and cleanup, not commit or external acknowledgement. submit() is the bounded external-thread entry. Only replaceable snapshots may declare snapshot_key. Existing events, Jobs, WebSockets and hosted callbacks retain their semantics. See the usage guide and reference module. Existing applications may explicitly adopt the sample; upgrades do not rewrite their code or generated documentation.

User entry migration (0.4)

• @exposes_application_services(ContractsModule) now contributes the formal Module dependency. Remove the repeated ContractsModule entry from the HTTP Module's dependencies; keep required transport capabilities. Conventional methods remain automatic, remote_service(is_enabled=False) excludes them, and route overrides still handle deliberate URL/operation identity differences.
• A plain Pydantic DTO on a generated GET endpoint binds to query parameters. Use explicit Body, Query, Header or Depends to select another native binding. Applications that intentionally sent GET bodies must now declare Body; complex parameter shapes retain FastAPI's native limits.
• Construct schedules as BackgroundJobSchedule(name="orders.daily", cron="0 0 * * *", job=JobType, payload=Payload(...)). A registered function's BackgroundJobDefinition is also accepted. Remove caller-supplied job_name, job_version and JSON bytes. Keep existing schedule names and Job definitions to retain durable identity; enqueue and PgQueuer storage are unchanged.
• Pass a RealtimeMessage subclass instance to send_to_user(user_id, message), send_to_connection(connection_id, message) or connection.send(message). Put the existing versioned name in the class's message_type and declare its payload fields with Pydantic. Preserve existing names/fields when migrating clients. The envelope and queue acceptance report retain their meaning.
• locks.acquire(key, wait_timeout=timedelta(...)) overrides only that acquisition's waiting time; None uses configured waiting and zero tries without waiting. Lease/renewal settings remain global.
• SettingManager.update now pairs SettingDefinition[T] with value: T; validate dynamic input at its boundary. Version tokens, reset and refresh behavior are unchanged. BusinessError(..., data=PublicData(...)) optionally publishes a Pydantic DTO under error.data; absence omits the field. Include only intentionally public fields, never raw exceptions or SQL.

See the usage guide for typed examples. Slice 5 is implemented; current extension/Identity migrations are documented below; the new consumer layout remains pending.

CLI module layout migration (0.4)

New modules use the responsibility directory rules, delivered inside each generated project. Existing applications are not regenerated by pddd upgrade.

• Replace the former <Module>ApplicationService with <Module>QueryApplicationService, <Module>ManagementApplicationService, and <Module>ApprovalApplicationService; the consumer item example has a separate item service. Inject the contract for the called use case.
• Move contracts from application_contracts/orders.py into services, inputs, and views; internal reporting goes in integration_services. Move aggregate/value/event/repository declarations into their Domain responsibility directories. Import the precise owner, without legacy aliases.
• Shared immutable values used by Domain and public DTOs belong in domain_shared/value_objects; domain-only values remain in domain/value_objects. The Catalog consumer moves Money out of domain_shared/values.py without changing its validation or normalization.
• Move application/tasks.py declarations into background_jobs/order_approval, background_workers, and their capability files. Hosted integration belongs in hosted_services; ORM Base belongs in sqlalchemy/models/base.py. Update tests and explicit registrations along with imports.
• Preserve external HTTP identities through the existing public route overrides. Keep Worker admission and HostedService/schedule enablement explicit; do not change existing schema, transactions, event ordering, or resource cleanup as part of this source migration. Merge the generated AGENTS/development conventions into application-owned documentation deliberately.

Identity migration (0.4)

Slice 7 adds user/role management and an application-local authorization switch. Existing public service contracts change without compatibility aliases.

• Apply pddd db upgrade --module identity before running the new code. The new identity_0004 revision adds concurrency_version to users and roles with a non-null initial value; published revisions and token formats remain unchanged. Consumer extension columns/indexes and revisions stay in the consumer project.
• get_users(query) and get_roles(query) accept PagedResultRequestDto and return PagedResult (items, total_count). Update callers that expected a bare array, custom repository implementations, and subclasses of the public defaults. New management DTOs are exported from python_ddd_framework.identity.
• Read concurrency_version from the current user/role or relationship view and supply it for edits, activation, deletion, passwords, and whole-set relationship updates. Relationship writes return the resulting version. HTTP DELETE takes a JSON version command. Handle 409 by rereading and resolving the edit; do not replace the supplied version and retry blindly. permission_version remains internal authorization cache state.
• Current-user password changes use ChangePasswordCommand with the old password and the version returned by me(). Administrator resets use SetPasswordCommand and the existing user-management permission. Password changes, deactivation, and deletion invalidate existing sessions after commit. Permission changes are reconsidered on subsequent requests.
• Access/refresh lifetimes and lockout controls now belong to IdentityOptions; defaults are preserved. Replace imports of the removed module-level duration/attempt constants with the owning Options. Existing refresh sessions use the currently configured lifetimes.
• AuthorizationOptions.always_allow defaults to False. Configure authorization.always_allow in the Host when authorization bypass is intended. It covers shared service/HTTP authorization without synthesizing identity or accepting invalid tokens; business validation, transactions, password checks, and realtime identity requirements remain active. Keep permission declarations so disabling the setting restores normal authorization.

See the Identity guide and validation limits. Consumer delivery is described in the layout migration below; fresh acceptance and remaining release limits are recorded on the status page.

Extension migration (0.4)

• Identity exposes DefaultAuthenticationApplicationService and DefaultIdentityManagementApplicationService. Specialize these public defaults and use the existing module override registration; keep policies on the final methods. Remove imports of the former private implementations.
• UserView is now a Pydantic ExtensibleModel; construct it with named arguments. CreateUserCommand, UpdateUserCommand, UserView (including paged results), and IdentityUser share IDENTITY_USER_EXTENSION. Declare typed ExtensionProperties through ModelExtensions; unknown fields are rejected. HTTP extension values remain inside extra_properties, including properties mapped to SQL columns.
• Nested DTOs and native Pydantic generic containers use the same Application-specific schema. Property types must be closed, including type aliases; nested models and dataclasses must reject unknown fields. Keep explicit Query/Header/Body bindings on the implementation when using a separate service contract.
• Upgrade Identity with pddd db upgrade --module identity before using the new JSON container (identity_0003). Never edit an applied base revision. A custom Identity store must preserve IdentityUser.extra_properties; SQL stores use the Application's SqlAlchemyModelCatalog.extension_model binding for queries and reads/writes.
• For independent columns, the consumer persistence Module contributes SqlAlchemyModelExtension and SqlAlchemyExtensionMigrations. Register that Module's CLI alias in project metadata, create its local migrations package, and declare the required base revision in depends_on. Do not register the base table or Schema again.
• After upgrading the base, run pddd db revision --module employee, review the generated file in the consumer extension module, then run pddd db upgrade --module employee and pddd db status --module employee. Replace employee with your declared alias. Generation includes only that extension's declared columns/indexes; installed framework files remain read-only. A standalone extension upgrade rejects missing prerequisites; the programmatic global migrator follows Alembic dependencies.
• When a later extension change requires a newer base revision, update the declaration's depends_on, apply that base revision, then generate the next extension revision. Earlier extension files keep their original dependencies. Upgrade/status require each current extension head to satisfy the current declaration.
• Plan explicit data migrations for backfills, required new properties on existing rows, or destructive changes. Host startup never changes tables. Declaration and storage examples are in the extension guide.

Upgrading

Framework upgrades update dependencies. They do not regenerate your business code, Host, configuration, templates, or migrations. Updating a globally installed CLI also leaves existing projects unchanged.

1. Read the target release's migration notes. Pin both python-ddd-framework in runtime dependencies and python-ddd-framework[developer-kit] in the development group to the same target version.
2. When adopting the unified installation layout, use python-ddd-framework==<version> for runtime dependencies and remove the old capability extras. Legacy extra names and [all] are not retained. Preserve the application's own dependencies and sources.
3. When moving a local-wheel or old Git installation to PyPI, remove only the framework's entry in [tool.uv.sources]. Keep unrelated source overrides and vendor files.
4. Apply any required source and configuration changes, update the environment, and run your application's validation:

uv lock --upgrade-package python-ddd-framework
uv sync --locked
uv run pytest
uv build --no-sources

During 0.x, compatible fixes use a patch release; changes requiring consumer adaptation use a minor release with migration instructions. Publishing changed package contents requires a new version. Release evidence, including the limits of previously tested upgrade paths, is recorded in status.

Migration notes

These notes remain the authoritative consumer migration instructions. Historical versions below refer to the former package name.

Additional fixes in 0.4.0

BackgroundJobRetryPolicy.max_attempts now counts all executions, including the first. A value of 2 permits two executions; 1 disables failure retries. The 0.3.2 PgQueuer mapping allowed one extra execution. If your application intentionally relied on that behavior, increase its configured total by one. BackgroundJobContext.attempt remains zero-based. No queue schema migration is required.

The developer-kit dependency constrains binaryornot to 0.5.x, because 0.6.0 can classify bundled templates containing Chinese comments as binary and skip rendering them. Re-resolve the developer-kit environment when installing 0.4.0. Updating the dependency does not replace existing generated application code.

The new DomainService marker uses existing constructor injection and transient REQUEST lifetime. It does not create transactions or expose HTTP endpoints. Newly generated modules place approval policy in domain/services/order_approval_service.py; existing projects can adopt that example explicitly after upgrading. The application checks existence and the submitted version before the domain policy; a stale or missing order therefore takes precedence over a disabled approval setting when both inputs are invalid. Domain rules, schema, and installation files are not automatically rewritten.

Documentation

The engineering guides below are maintained in Chinese in the private GitHub repository and require repository access. This README and the documents bundled with generated applications provide the English product and development guides.

Generated applications include a self-contained English README, AGENTS.md, architecture document, and development guide for their template version. AGENTS.md directs Codex and other contributors to the affected guidance and module README. Each document has a distinct owner, and the application maintains them after generation; framework upgrades do not overwrite them.

License

Python DDD Framework is distributed under the hank-repo Proprietary License. Use requires a separate written agreement; public package availability does not grant additional rights. The source repository is private, with public PyPI packages as the intended delivery channel. PgQueuer-derived code retains its upstream license.

Consumer layout migration (0.4)

Move an existing application's Python project files, configuration, source, tests, lockfile, vendor wheels, and deployment files into backend/; keep application documentation and consumer-owned scripts/ at the root. Recreate .venv with uv sync --project backend instead of moving an environment. Update relative script/deployment paths and module README links. Keep portable Python declarations in backend/.python-version and backend/pyproject.toml. Use installed pddd from any application directory, or uv run pddd inside backend/. Module aliases remain standard entry points and runtime types remain AppModule; template selection adds no registration or compatibility path.