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

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

Built distribution (wheel)

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

Total release size: 41.5 kB

Release files / python_cq-0.27.1.tar.gz

Download URL python_cq-0.27.1.tar.gz
Size 17.2 kB
Tags Source
SHA-256 checksum
How to use checksums
0d3096cabc04814c2c7e16a2dc93bc36841e023000b8c3a1b333be69fb5eab1c
BLAKE2b-256 checksum
How to use checksums
fe4668b238f19e77c39baa21238e5bc1dd43c0a8d5c857718edba5d8f7211ecd
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.1-py3-none-any.whl

Download URL python_cq-0.27.1-py3-none-any.whl
Size 24.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
fe61a2aef9c94f1c8511ae8ebf33a2af567250dbf2302575816eb18dbe0f51d3
BLAKE2b-256 checksum
How to use checksums
ad50400e14651019e9d1808c50a96d43246d551d950441bc9ac127ba5e9d68b5
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.1

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