waku-py/waku

Waku is a Python application framework that provides a structured environment for building modular applications with a focus on dependency injection, messaging, and event sourcing. It offers a unified messaging bus supporting CQRS and pipeline behaviors, alongside a complete event sourcing system with aggregate and decider support. The framework emphasizes code quality through automated linting and type checking, and includes a robust extension system for managing application lifecycle and module initialization.

7 changes.

The project underwent a significant architectural shift by introducing the new Waku application framework and a simplified dependency injection system built on Dishka. This period focused on replacing legacy modular components with a structured development workflow, updated tooling, and comprehensive test coverage for the new validation rules.

9 changes.

This period focused on introducing a robust dependency injection and module system, featuring a new ModuleRegistry, extension lifecycle hooks, and a validation framework for dependency accessibility. Comprehensive test coverage was added to verify the behavior of the DI framework, extension registry, and testing utilities.

11 changes.

This period focused on implementing and testing two major new subsystems: an event sourcing framework with aggregate and decider support, and a unified messaging bus with explicit routing and pipeline behaviors. Comprehensive test suites were added for both domains, covering storage backends, projection runners, snapshotting, and message dispatching.

Added example code demonstrating event sourcing with an in-memory store and a PostgreSQL store, including domain models, command handlers, and module wiring.

examples/eventsourcing · high confidence

The changelog generation system has been replaced with a new set of Jinja2 templates in the config directory. This introduces a modular structure for generating both the project's CHANGELOG.md and individual release notes, featuring dedicated sections for breaking changes and release notes, alongside standard feature and bug fix listings.

config · high confidence

The project now enforces a structured development workflow with automated code quality checks. Pre-commit hooks are configured to run linting (Ruff), type checking (MyPy, Ty, Pyrefly), spell checking (Typos), and dependency auditing (pysentry-rs) on every commit and push. A custom gitlint rule ensures all commit messages follow the Conventional Commits format with allowed scopes (core, messaging, di, etc.). The repository includes configuration files for these tools (\.pre-commit-config.yaml\, \.gitlint\, \.typos.toml\, \pyrefly.toml\), a \Taskfile.yml\ with tasks for linting, type-checking, and testing, and updated documentation in \README.md\ and \CONTRIBUTING.md\ to guide contributors.

(repo-wide) · high confidence

The \src/waku\ package now provides a new application framework called Waku. This includes a \WakuApplication\ class that manages the application lifecycle and integrates with the \dishka\ dependency injection container. The framework exposes a \WakuFactory\ for building applications and an \ExtensionRegistry\ system that supports module and application-level hooks (such as \OnModuleInit\, \OnApplicationInit\, and \OnApplicationShutdown\). Additionally, a \testing\ module is provided with a \create\_test\_app\ helper and an \override\ context manager to facilitate unit testing by allowing temporary provider and context overrides.

src/waku · high confidence

The framework now supports a structured extension system that allows modules and the application to hook into specific lifecycle events. New protocols define hooks for application initialization, shutdown, and module registration, configuration, initialization, and destruction. An \ExtensionRegistry\ has been added to centrally manage and discover these extensions, enabling cross-module aggregation and provider contribution during the module registration phase.

src/waku/extensions · high confidence

The new \waku.eventsourcing\ package provides a complete event sourcing implementation. It introduces \EventSourcedRepository\ and \DeciderRepository\ for managing aggregate state and decider-based workflows, along with \EventSourcedCommandHandler\ and \DeciderCommandHandler\ for processing commands with optimistic concurrency retry. The module also includes a catch-up projection system (\CatchUpProjectionRunner\, \ICatchUpProjection\) with configurable error policies, gap detection, and checkpointing. Additional features include snapshotting, event upcasting, idempotency key handling, and structured logging for events.

src/waku/eventsourcing · high confidence

Added a new validation subsystem in src/waku/validation that enforces dependency accessibility rules across modules. The framework includes a ValidationRule protocol, a ValidationExtension that runs after application initialization, and a specific rule (DependenciesAccessibleRule) that checks whether all required dependencies are accessible to each module. The implementation includes helper classes for caching type extractions (LRUCache, ModuleTypesExtractor) and strategies for checking global, local, context, and imported module accessibility. If inaccessible dependencies are found, the system raises a ValidationError (or warns in non-strict mode).

src/waku/validation · medium confidence

A new \waku.di\ package has been introduced, wrapping the \dishka\ library to provide a more ergonomic API for dependency injection. This includes helper functions to create providers for singletons, scoped (request) lifetimes, and transient lifetimes, as well as a \many\ helper for registering multiple implementations as a collection. The module also exposes \contextual\ resolution and conditional activation via markers, allowing users to register dependencies with simplified syntax while retaining \dishka\'s underlying capabilities.

src/waku/di · high confidence

Added four new example files in the examples directory that showcase advanced dependency injection capabilities. The examples demonstrate conditional provider activation using custom markers and activators, contextual provider registration for request-scoped data, improved interface-to-implementation binding patterns, and modular application composition with dynamic module registration.

examples · high confidence

Added new example files in the messaging directory that demonstrate the framework's messaging capabilities. basic\_usage.py shows how to define and handle CQRS commands and events. message\_context.py illustrates how to access message context for correlation and causation tracking. pipeline\_behaviors.py demonstrates how to implement and register pipeline behaviors for cross-cutting concerns. routing.py shows how to configure local queue endpoints and use route\_module() and route() for module-level and per-type event routing.

examples/messaging · high confidence

The messaging subsystem has been refactored into a unified message bus that supports request/response invocation, fire-and-forget sending, and fan-out publishing. Routing is now explicit via \route()\ and \route\_module()\ descriptors that map message types to endpoint URIs, with per-type routes taking precedence over module-level routes. The system introduces a configurable pipeline behavior system, including a built-in \TransactionalBehavior\ that commits or rolls back a database unit of work around message handling. A \MessageContext\ provides correlation and causation headers during processing, and the dispatcher enforces strict handler registration to prevent silent failures.

src/waku/messaging · high confidence

A new JavaScript widget from Context7 has been added to the site's header via the main template override. This introduces a third-party script that loads a widget for the 'waku' library with a specific color theme, making the widget available across all pages that use the base template.

overrides · medium confidence

The module system has been refactored to use a new \ModuleRegistry\ and \ModuleMetadata\ architecture, enabling structured dependency injection via the \dishka\ library. Users can now define modules with explicit imports, exports, and providers, while lifecycle hooks like \OnModuleRegistration\ and \OnModuleConfigure\ allow for extensible initialization and configuration. This change provides a more robust and type-safe way to manage module dependencies and extensions.

src/waku/modules · high confidence

The \src/lattice\ package has been refactored by removing several core components: the generic dependency injection abstractions (\di.py\), the \Module\ and \Application\ classes (\module.py\), the \ApplicationModule\ and \Application\ classes (\modules.py\), the \OnApplicationInit\ protocol (\extensions.py\), the \aioinject\ integration (\contrib/aioinject.py\), the \mediatr\ middleware support (\ext/mediatr/middlewares.py\), and the module validation logic (\validation.py\). This removes the previous modular, validation-driven application structure in favor of a new implementation.

src/lattice · high confidence

Added comprehensive test coverage for the dependency injection system; Added comprehensive tests for event sourcing projection subsystem; Added comprehensive tests for the new messaging subsystem; Added tests for dependency accessibility validation; Added tests for dynamic module configuration and metadata isolation; Added tests for event sourcing decider and snapshot repository; Added tests for event sourcing snapshot functionality; Added tests for event sourcing store implementations; Added tests for the event sourcing module; Added tests for the extension system and module lifecycle; Added tests for the testing utilities and override functionality; Restructured test suite with shared fixtures and utilities.

The project's dependency manifest (pyproject.toml) has been updated to specify newer versions of key libraries, including dishka (\>=1.9.1), anyio (\>=4.13.0), and typing-extensions (\>=4.15.0). Development tooling has also been upgraded, with pytest moving to v9.0.2, ruff to v0.15.8, and mypy to v1.19.1. Additionally, the build system has been migrated to use uv\_build, and the project name has been changed to 'waku' with version 0.43.0.

(dependencies) · high confidence

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

• CAI 71 → 77 (+5.5)
• Rubric changed (rubric-2026.08.19 → rubric-2026.09.15) — scores are not directly comparable.

• Code Health 99 → 99 (+0.1)
• Architecture 97 → 87 (-9.6)
• Maturity 72 → 77 (+4.7)
• Readiness 60 → 70 (+9.7)
• Security 78 → 82 (+4.0)
• Domain Modelling 100 → 100 (+0.0)

• Change coupling: exceptions.py ↔ repository.py (src/waku/eventsourcing/exceptions.py)
• Change coupling: factory.py ↔ _metadata.py (src/waku/factory.py)
• Change coupling: repository.py ↔ exceptions.py (src/waku/eventsourcing/decider/repository.py)
• Change coupling: repository.py ↔ repository.py (src/waku/eventsourcing/decider/repository.py)
• Coverage not included — suite not readable by the collector
• Dependency hygiene not measured — dependency manifest found but not parsed for hygiene
• Duplicated block (9 lines × 2) (examples/eventsourcing/basic_usage.py)
• High CVE: [GHSA redacted] (uv.lock)
• High CVE: [GHSA redacted] (uv.lock)
• LLM evaluation failed
• Medium CVE: [GHSA redacted] (uv.lock)
• Medium CVE: [GHSA redacted] (uv.lock)
• Medium CVE: [GHSA redacted] (uv.lock)
• Medium CVE: PYSEC-2026-2132 (uv.lock)
• Medium CVE: PYSEC-2026-2987 (uv.lock)
• No exposed public API
• Off-boarding risk: anonymized user #1
• PR-triggered workflow without a permissions block
• Test reliability not included

• Critical CVE: [GHSA redacted] (uv.lock)
• Dependency hygiene PARTLY measured — Python dependencies read, no exact pin to grade for currency
• Documentation: contradicts the code
• Documentation: no installation or build instructions (README.md)
• Documentation: no installation or build instructions (docs/contributing/docs.md)
• Documentation: no project overview (docs/features/index.md)
• Duplicated block (13–16 lines × 2) (examples/eventsourcing/basic_usage.py)
• Duplicated block (8 lines × 3) (docs/code/eventsourcing/quickstart/aggregate.py)
• Fork-triggerable workflow runs with an unscoped write token
• High CVE: [GHSA redacted] (uv.lock)
• High CVE: [GHSA redacted] (uv.lock)
• High CVE: [GHSA redacted] (uv.lock)
• Medium CVE: [GHSA redacted] (uv.lock)
• Medium CVE: [GHSA redacted] (uv.lock)
• Medium CVE: PYSEC-2026-2132 (uv.lock)
• Medium CVE: PYSEC-2026-2987 (uv.lock)
• TodoComment (src/waku/messaging/endpoints/local_queue.py)
• TodoComment (src/waku/messaging/modules.py)

Written by watchdog.canine.dev from the codebase's own history, inside the signed delivery this page is composed from.

waku-py/waku was measured the same way every project in this corpus was: the same rubric, at a pinned commit, with the result published in full. Point a surveyor at a repository you know and see whether you agree with it.