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

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
File Size Uploaded Provenance Actions
python_cq-0.27.0.tar.gz 17.0 kB Without provenance Details for python_cq-0.27.0.tar.gz

Built distribution (wheel)

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

Total release size: 41.2 kB

Release files / python_cq-0.27.0.tar.gz

Download URL python_cq-0.27.0.tar.gz
Size 17.0 kB
Tags Source
SHA-256 checksum
How to use checksums
4821aca82b25e635095597aa7ca5b5037ca17d286af1275a91b31975ef3bcda5
BLAKE2b-256 checksum
How to use checksums
7e07e6d1f157dfdcf669bc907c599809b2327f34a0eb38843a3bc1326f32be91
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-py3-none-any.whl

Download URL python_cq-0.27.0-py3-none-any.whl
Size 24.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
86a7528dc390ff0ba06b2d38533a5b99b4170c1a68e42862dfcc9997ee290064
BLAKE2b-256 checksum
How to use checksums
4c1188b67dd4eed6fd161dcccb6018040eae3021009c9f75e7755059ed778a53
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

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 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