Protean
Protean is an opinionated Python framework for building event-driven applications with Domain-Driven Design — aggregates, CQRS, and event sourcing are first-class, and your domain logic stays independent of the database, broker, and API you run it on.
Installation
Protean is available on PyPI:
$ pip install protean
Protean officially supports Python 3.11+.
Quick Start
A command flows to its handler, the aggregate raises an event, and an event handler reacts — all wired by the domain, independent of infrastructure:
from protean import Domain
from protean.fields import Boolean, Identifier, String
from protean.utils.mixins import handle
domain = Domain(name="Publishing")
domain.config["command_processing"] = "sync"
domain.config["event_processing"] = "sync"
@domain.event(part_of="Post")
class PostPublished:
post_id = Identifier()
title = String()
@domain.aggregate
class Post:
title = String(required=True, max_length=200)
is_published = Boolean(default=False)
def publish(self):
self.is_published = True
self.raise_(PostPublished(post_id=self.id, title=self.title))
@domain.command(part_of="Post")
class PublishPost:
post_id = Identifier(identifier=True)
title = String()
@domain.command_handler(part_of="Post")
class PostCommandHandler:
@handle(PublishPost)
def publish(self, command):
post = Post(id=command.post_id, title=command.title)
post.publish()
domain.repository_for(Post).add(post)
@domain.event_handler(part_of="Post")
class Notifications:
@handle(PostPublished)
def announce(self, event):
print(f"Published: {event.title}")
domain.init(traverse=False)
with domain.domain_context():
domain.process(PublishPost(post_id="1", title="Hello, Protean"))
Documentation
Online docs are available at https://docs.proteanhq.com.
Versioning
Protean does not use strict semantic versioning. The promise is: Code that runs warning-free on 1.N runs unmodified on 1.N+1. Every removal is announced by a deprecation warning naming the release it lands in, at least one release ahead, so you can turn "will this upgrade break us?" into a test run. See the versioning policy for the full contract.
Quality
Protean is tested against 5 backing services across 4 Python versions on every commit.
| Metric | Value |
|---|---|
| Tests | 12,000+ (quality report) |
| Linting | Zero violations (Ruff) |
| Complexity | Avg 3.38 cyclomatic (A grade) |
| Maintainability | A rank (95% of files) |
| CI Matrix | Python 3.11-3.14 x PostgreSQL, Redis, Elasticsearch, MessageDB, MSSQL |
See the full Quality Report for details.
Contributing
Note: Protean framework is not associated or related to Protean eGov Technologies or Code for Gov Tech initiatives.
Protean is developed and maintained by a single maintainer. The contributions that help most are bug reports, real-world use cases, and adapter packages built against the public conformance suite.
- Found a bug or have a use case to share? Open an issue. Clear, reproducible reports are the most valuable contribution you can make, and they are answered as a priority.
- Planning a non-trivial code change? Open an issue to discuss it first, before investing in a pull request. Unsolicited large PRs may not be merged. Small, obvious fixes are welcome directly.
- Building an adapter? Adapters live in their own packages, certified against the conformance suite. See the contributing guide.
See CONTRIBUTING.md and the community section for the full picture.
License
Protean is licensed under the Apache License 2.0.
Licensing commitment. The Protean framework core is, and will remain, available under the Apache License 2.0. This is a permanent commitment: the core will not be relicensed to a proprietary or source-available license.
Copyright 2018-2026 Subhash Bhushan C and the Protean contributors.
1 maintainer
Metadata
1 maintainer
Release files for protean 0.17.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| protean-0.17.1.tar.gz | 4.9 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| protean-0.17.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 6.2 MB
Release files / protean-0.17.1.tar.gz
| Download URL | protean-0.17.1.tar.gz |
|---|---|
| Size | 4.9 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
88e568faffeda8692f0dcb46e52627bddb9525e83c1880eb47ca25e685ef6b70
|
|
BLAKE2b-256 checksum How to use checksums |
de8db832a50db00d13dbeb288bb312c632572a165ed572f33e7d5324cba43f86
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 12, 2026.
Transparency logRelease files / protean-0.17.1-py3-none-any.whl
| Download URL | protean-0.17.1-py3-none-any.whl |
|---|---|
| Size | 1.2 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f1573bcd582994aa7da06911977f31020bc8199c58a90289113b337bc190a3cb
|
|
BLAKE2b-256 checksum How to use checksums |
ebdd9f36a03c6e3d6152b3cbf31b67d0eb34f9e0f85d8c74cb952b8ba27b139e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 12, 2026.
Transparency log
