Metadata-Version: 2.5
Name: protean
Version: 0.17.1
Summary: An opinionated DDD, CQRS, and event-sourcing framework for Python
Project-URL: Homepage, https://docs.proteanhq.com
Project-URL: Documentation, https://docs.proteanhq.com
Project-URL: Repository, https://github.com/proteanhq/protean
Project-URL: Issues, https://github.com/proteanhq/protean/issues
Project-URL: Changelog, https://github.com/proteanhq/protean/blob/main/CHANGELOG.md
Author-email: Subhash Bhushan C <subhash@team8solutions.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: aggregates,asynchronous,bounded-contexts,clean-architecture,cqrs,cqrs-framework,ddd,domain-driven-design,entities,event-driven-architecture,event-sourcing,event-sourcing-framework,hexagonal-architecture,microservices,onion-architecture,python-framework,repository-pattern,services,value-objects
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Pytest
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: System :: Distributed Computing
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: bleach>=6.1.0
Requires-Dist: cffi>=2.0.0
Requires-Dist: copier<10,>=9.4.0
Requires-Dist: fastapi>=0.139.0
Requires-Dist: greenlet<4,>=3.2.3
Requires-Dist: inflection>=0.5.1
Requires-Dist: ipython<10.0,>=9.0.0
Requires-Dist: jinja2>=3.1.6
Requires-Dist: marshmallow>=4.0.0
Requires-Dist: pydantic<3.0,>=2.12.0
Requires-Dist: python-dateutil>=2.8.2
Requires-Dist: structlog>=24.1.0
Requires-Dist: typer>=0.16.0
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: werkzeug>=3.1.0
Provides-Extra: dev
Requires-Dist: watchfiles>=1.2.0; extra == 'dev'
Provides-Extra: elasticsearch
Requires-Dist: elasticsearch<9.0.0,>=8.18.0; extra == 'elasticsearch'
Provides-Extra: flask
Requires-Dist: flask>=3.0.0; extra == 'flask'
Provides-Extra: message-db
Requires-Dist: message-db-py>=0.3.4; extra == 'message-db'
Provides-Extra: mssql
Requires-Dist: pyodbc>=5.3.0; extra == 'mssql'
Requires-Dist: sqlalchemy<2.1,>=2.0.36; extra == 'mssql'
Provides-Extra: postgresql
Requires-Dist: psycopg2-binary>=2.9.11; extra == 'postgresql'
Requires-Dist: sqlalchemy<2.1,>=2.0.36; extra == 'postgresql'
Provides-Extra: redis
Requires-Dist: redis<8.1.0,>=8.0.0; extra == 'redis'
Provides-Extra: sendgrid
Requires-Dist: sendgrid>=6.11.0; extra == 'sendgrid'
Provides-Extra: sqlite
Requires-Dist: sqlalchemy<2.1,>=2.0.36; extra == 'sqlite'
Provides-Extra: telemetry
Requires-Dist: opentelemetry-api>=1.36.0; extra == 'telemetry'
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc>=1.36.0; extra == 'telemetry'
Requires-Dist: opentelemetry-exporter-prometheus>=0.57b0; extra == 'telemetry'
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.57b0; extra == 'telemetry'
Requires-Dist: opentelemetry-sdk>=1.36.0; extra == 'telemetry'
Description-Content-Type: text/markdown

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

[![Python](https://img.shields.io/pypi/pyversions/protean?label=Python)](https://github.com/proteanhq/protean/)
[![Release](https://img.shields.io/pypi/v/protean?label=Release&style=flat-square)](https://pypi.org/project/protean/)
[![Build Status](https://github.com/proteanhq/protean/actions/workflows/ci.yml/badge.svg)](https://github.com/proteanhq/protean/actions/workflows/ci.yml)
[![Coverage](https://codecov.io/gh/proteanhq/protean/graph/badge.svg?token=0sFuFdLBOx)](https://codecov.io/gh/proteanhq/protean)
[![Tests](https://img.shields.io/badge/tests-12%2C000%2B-brightgreen)](https://docs.proteanhq.com/community/quality/)
[![Maintainability](https://img.shields.io/badge/maintainability-A-brightgreen)](https://docs.proteanhq.com/community/quality/)

## Installation

Protean is available on PyPI:

```console
$ 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:

```python
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](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](https://docs.proteanhq.com/reference/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](https://docs.proteanhq.com/community/quality/)) |
| 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](https://docs.proteanhq.com/community/quality/) for details.

## Contributing

> **Note**: Protean framework is not associated or related to [Protean eGov Technologies](https://www.proteantech.in/) or [Code for Gov Tech](https://codeforgovtech.in/) 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](https://github.com/proteanhq/protean/issues). 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](https://docs.proteanhq.com/community/contributing/setup/).

See [CONTRIBUTING.md](CONTRIBUTING.md) and the
[community](https://docs.proteanhq.com/community/) section for the full picture.

## License

Protean is licensed under the [Apache License 2.0](LICENSE).

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