Skip to main content

python-cq

PyPI - Version PyPI - Downloads

python-cq is an async-first Python library for organizing code around CQRS. It routes commands, queries, and events to their handlers through dedicated buses, and lets you put a queue in front of any of them when a message should be processed later. Dependency injection is pluggable behind a small protocol.

The library is made of two independent parts:

  • Routing: messages, handlers, buses, middlewares, and command pipelines. This is the core of the library and what most applications need.
  • Queuing: a Queue protocol and a Pump that drains a queue into any async callable, typically a bus.

You can use routing without ever touching queuing, and the queuing primitives work with any dispatcher, not only the buses of this library.

What is CQRS?

CQRS (Command Query Responsibility Segregation) splits read operations from write operations. Each operation has a single, well-defined responsibility, which:

  • clarifies intent: a CreateUserCommand does one thing, and its name says so;
  • keeps handlers small: one message, one handler, easy to test in isolation;
  • makes side effects explicit: events fan out to subscribers without coupling the producer to them.

CQRS is often discussed alongside distributed systems and Event Sourcing, but the pattern is just as useful in a local or monolithic application. The boundaries it draws are valuable on their own.

Three message types

Type Intent Handlers Returns
Command Change the state of the system Exactly one The handler's return value
Query Read state without side effects Exactly one The handler's return value
Event Notify that something has happened Zero, one, or many Nothing

A Command is allowed to return a value (for convenience, typically an id or a result object), but that does not make it a query. Keep intent clear.

Installation

Requires Python 3.12 or higher.

With the default DI backend (python-injection, recommended):

pip install "python-cq[injection]"

Without dependency injection (you will need to implement a DIAdapter to inject anything into your handlers):

pip install python-cq

Quickstart

import asyncio
from cq import CommandBus
from cq.default import command_handler
from dataclasses import dataclass
from injection import inject


@dataclass
class CreateUserCommand:
    name: str
    email: str


@command_handler
class CreateUserHandler:
    async def handle(self, command: CreateUserCommand) -> int:
        # ... persist the user, return its id
        return 42


@inject
async def main(bus: CommandBus[int]) -> None:
    command = CreateUserCommand(name="Ada", email="ada@example.com")
    user_id = await bus.dispatch(command)
    print(f"Created user {user_id}")


asyncio.run(main())

The decorator registers the handler against the type annotation of the first handle parameter. The bus is resolved by the DI container and forwards the command to that handler.

Prerequisites

Familiarity with the following helps you get the most out of python-cq:

  • CQRS, in particular the distinction between Commands, Queries, and Events.
  • Domain Driven Design (DDD), particularly aggregates and bounded contexts, which complement CQRS well.

Metadata

Release files for python-cq 0.27.0.post0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for python-cq 0.27.0.post0
File Size Uploaded Provenance Actions
python_cq-0.27.0.post0.tar.gz 17.2 kB Without provenance Details for python_cq-0.27.0.post0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for python-cq 0.27.0.post0
File Interpreter ABI Platform Actions
python_cq-0.27.0.post0-py3-none-any.whl Python 3 none any Details for python_cq-0.27.0.post0-py3-none-any.whl

Total release size: 41.6 kB

Release files / python_cq-0.27.0.post0.tar.gz

Download URL python_cq-0.27.0.post0.tar.gz
Size 17.2 kB
Tags Source
SHA-256 checksum
How to use checksums
5ef33f8486a48714260749f6d60b662b5f0ac071709df92b5976a6e4b25794fd
BLAKE2b-256 checksum
How to use checksums
99431672da96163111e5b65d3e3723197f360e6179476c08086d61e0e2c70fa7
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / python_cq-0.27.0.post0-py3-none-any.whl

Download URL python_cq-0.27.0.post0-py3-none-any.whl
Size 24.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
48cb343c485adc380295b478a103fc3986030082c751a9c30b564e92a9ac5e85
BLAKE2b-256 checksum
How to use checksums
7c3d13e19b9ab4f188375b5f06a8a406222dac4b2cc5425b63b6720a12616cf2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for python-cq 0.27.0.post0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.27.0.post0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page