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.

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.