| Name | propan JSON |
| Version |
0.1.5.26
JSON |
| download |
| home_page | |
| Summary | Propan framework: the simplest way to work with a messaging queues |
| upload_time | 2024-01-15 16:36:43 |
| maintainer | |
| docs_url | None |
| author | |
| requires_python | >=3.8 |
| license | |
| keywords |
framework
kafka
message brokers
nats
rabbitmq
redis
sqs
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<a href="https://lancetnik.github.io/Propan/" target="_blank">
<img src="https://lancetnik.github.io/Propan/assets/img/logo-no-background.png" alt="Propan logo" style="height: 250px; width: 600px;"/>
</a>
</p>
<p align="center">
<a href="https://github.com/Lancetnik/Propan/actions/workflows/tests.yml" target="_blank">
<img src="https://github.com/Lancetnik/Propan/actions/workflows/tests.yml/badge.svg" alt="Tests coverage"/>
</a>
<a href="https://coverage-badge.samuelcolvin.workers.dev/redirect/lancetnik/propan" target="_blank">
<img src="https://coverage-badge.samuelcolvin.workers.dev/lancetnik/propan.svg" alt="Coverage">
</a>
<a href="https://pypi.org/project/propan" target="_blank">
<img src="https://img.shields.io/pypi/v/propan?label=pypi%20package" alt="Package version">
</a>
<a href="https://pepy.tech/project/propan" target="_blank">
<img src="https://static.pepy.tech/personalized-badge/propan?period=total&units=international_system&left_color=grey&right_color=blue&left_text=Downloads" alt="downloads"/>
</a>
<br/>
<a href="https://pypi.org/project/propan" target="_blank">
<img src="https://img.shields.io/pypi/pyversions/propan.svg" alt="Supported Python versions">
</a>
<a href="https://github.com/Lancetnik/Propan/blob/main/LICENSE" target="_blank">
<img alt="GitHub" src="https://img.shields.io/github/license/Lancetnik/Propan?color=%23007ec6">
</a>
<a href="https://discord.gg/ChhMXJpvz7" target="_blank">
<img alt="Discord" src="https://img.shields.io/discord/1122560426794831872?logo=discord">
</a>
</p>
# Propan
**Propan** - just *~~an another one HTTP~~* a **declarative Python Messaging Framework**. It's inspired by <a href="https://FastAPI.tiangolo.com/ru/" target="_blank">*FastAPI*</a> and <a href="https://docs.celeryq.dev/projects/kombu/en/stable/" target="_blank">*Kombu*</a>, simplify Message Brokers around code writing and provides a helpful development toolkit, which existed only in HTTP-frameworks world until now.
It's designed to create reactive microservices around <a href="https://microservices.io/patterns/communication-style/messaging.html" target="_blank">Messaging Architecture</a>.
It is a modern, high-level framework on top of popular specific Python brokers libraries, based on <a href="https://docs.pydantic.dev/" target="_blank">*pydantic*</a> and <a href="https://FastAPI.tiangolo.com/ru/" target="_blank">*FastAPI*</a>, <a href="https://docs.pytest.org/en/latest/" target="_blank">*pytest*</a> concepts.
---
## :warning::warning::warning: Deprecation notice :warning::warning::warning:
This project is superceeded by [**FastStream**](https://github.com/airtai/faststream).
**FastStream** is a new package based on the ideas and experiences gained from [**FastKafka**](https://github.com/airtai/fastkafka) and **Propan**. By joining our forces, we picked up the best from both packages and created a unified way to write services capable of processing streamed data regardless of the underlying protocol.
I’ll continue to maintain **Propan** package, but new development will be in **FastStream**. If you are starting a new service, **FastStream** is the recommended way to do it.
For now **FastStream** supports **Kafka** and **RabbitMQ**. Other brokers support will be added in a few months.
You can find a detail migration guide in the [documentation](https://lancetnik.github.io/Propan/migration/)
---
**Documentation**: <a href="https://lancetnik.github.io/Propan/" target="_blank">https://lancetnik.github.io/Propan/</a>
---
### The key features are
* **Simple**: Designed to be easy to use and learn.
* **Intuitive**: Great editor support. Autocompletion everywhere.
* [**Dependencies management**](#dependencies): Minimization of code duplication. Access to dependencies at any level of the call stack.
* [**Integrations**](#http-frameworks-integrations): **Propan** is fully compatible with <a href="https://lancetnik.github.io/Propan/integrations/1_integrations-index/" target="_blank">any HTTP framework</a> you want
* **MQ independent**: Single interface to popular MQ:
* **Redis** (based on <a href="https://redis.readthedocs.io/en/stable/index.html" target="_blank">redis-py</a>)
* **RabbitMQ** (based on <a href="https://aio-pika.readthedocs.io/en/latest/" target="_blank">aio-pika</a>)
* **Kafka** (based on <a href="https://aiokafka.readthedocs.io/en/stable/" target="_blank">aiokafka</a>)
* **SQS** (based on <a href="https://aiobotocore.readthedocs.io/en/latest/" target="_blank">aiobotocore</a>)
* **Nats** (based on <a href="https://github.com/nats-io/nats.py" target="_blank">nats-py</a>)
* <a href="https://lancetnik.github.io/Propan/getting_started/4_broker/6_rpc/" target="_blank">**RPC**</a>: The framework supports RPC requests over MQ, which will allow performing long operations on remote services asynchronously.
* [**Great to develop**](#cli-power): CLI tool provides great development experience:
* framework-independent way to manage the project environment
* application code *hot reload*
* robust application templates
* [**Documentation**](#project-documentation): **Propan** automatically generates and presents an interactive <a href="https://www.asyncapi.com/" target="_blank">**AsyncAPI**</a> documentation for your project
* <a href="https://lancetnik.github.io/Propan/getting_started/7_testing" target="_blank">**Testability**</a>: **Propan** allows you to test your app without external dependencies: you do not have to set up a Message Broker, you can use a virtual one!
### Supported MQ brokers
| | async | sync |
|-------------------|:-------------------------------------------------------:|:-------------------------------------------:|
| **RabbitMQ** | :heavy_check_mark: **stable** :heavy_check_mark: | :hammer_and_wrench: WIP :hammer_and_wrench: |
| **Redis** | :heavy_check_mark: **stable** :heavy_check_mark: | :mag: planning :mag: |
| **Nats** | :heavy_check_mark: **stable** :heavy_check_mark: | :mag: planning :mag: |
| **Kafka** | :warning: **beta** :warning: | :mag: planning :mag: |
| **SQS** | :warning: **beta** :warning: | :mag: planning :mag: |
| **NatsJS** | :warning: **beta** :warning: | :mag: planning :mag: |
| **ZeroMQ** | :hammer_and_wrench: WIP :hammer_and_wrench: | :mag: planning :mag: |
| **MQTT** | :mag: planning :mag: | :mag: planning :mag: |
| **Redis Streams** | :mag: planning :mag: | :mag: planning :mag: |
| **Pulsar** | :mag: planning :mag: | :mag: planning :mag: |
| **ActiveMQ** | :mag: planning :mag: | :mag: planning :mag: |
| **AzureSB** | :mag: planning :mag: | :mag: planning :mag: |
---
### ⭐ Support the project ⭐
If you are interested in this project, please give me feedback by:
- giving the [repository](https://github.com/Lancetnik/Propan) a star
- tweet about <a href="https://twitter.com/compose/tweet?text=I'm like @PropanFramework because... https://github.com/Lancetnik/Propan" class="external-link" target="_blank">**Propan**</a> and let me and others know why you use it
- joining <a href="https://discord.gg/ChhMXJpvz7" target="_blank">Discord server</a>
Your support helps me to stay in touch with you and encourages to
continue developing and improving the library. Thank you for your
support!
Really, share information about this project with others. The bigger community we have - the better project will be!
---
## Declarative?
With declarative tools you can define **what you need to get**. With traditional imperative tools you must write **what you need to do**.
Take a look at classic imperative tools, such as <a href="https://aio-pika.readthedocs.io/en/latest/" target="_blank">aio-pika</a>, <a href="https://pika.readthedocs.io/en/stable/" target="_blank">pika</a>, <a href="https://redis.readthedocs.io/en/stable/index.html" target="_blank">redis-py</a>, <a href="https://github.com/nats-io/nats.py" target="_blank">nats-py</a>, etc.
This is the **Quickstart** with the *aio-pika*:
```python
import asyncio
import aio_pika
async def main():
connection = await aio_pika.connect_robust(
"amqp://guest:guest@127.0.0.1/"
)
queue_name = "test_queue"
async with connection:
channel = await connection.channel()
queue = await channel.declare_queue(queue_name)
async with queue.iterator() as queue_iter:
async for message in queue_iter:
async with message.process():
print(message.body)
asyncio.run(main())
```
**aio-pika** is a great tool with a really easy learning curve. But it's still imperative. You need to *connect*, declare *channel*, *queues*, *exchanges* by yourself. Also, you need to manage *connection*, *message*, *queue* context to avoid any troubles.
It is not a bad way, but it can be much easier.
```python
from propan import PropanApp, RabbitBroker
broker = RabbitBroker("amqp://guest:guest@localhost:5672/")
app = PropanApp(broker)
@broker.handle("test_queue")
async def base_handler(body):
print(body)
```
This is the **Propan** declarative way to write the same code. That is so much easier, isn't it?
---
## Quickstart
Install using `pip`:
```shell
pip install "propan[async-rabbit]"
# or
pip install "propan[async-nats]"
# or
pip install "propan[async-redis]"
# or
pip install "propan[async-kafka]"
# or
pip install "propan[async-sqs]"
```
### Basic usage
Create an application with the following code at `serve.py`:
```python
from propan import PropanApp
from propan import RabbitBroker
# from propan import RedisBroker
# from propan import NatsBroker
# from propan import SQSBroker
# from propan import KafkaBroker
broker = RabbitBroker("amqp://guest:guest@localhost:5672/")
# broker = NatsBroker("nats://localhost:4222")
# broker = RedisBroker("redis://localhost:6379")
# broker = SQSBroker("http://localhost:9324", ...)
# broker = KafkaBroker("localhost:9092")
app = PropanApp(broker)
@broker.handle("test")
async def base_handler(body):
print(body)
```
And just run it:
```shell
propan run serve:app --workers 3
```
---
## Type casting
Propan uses `pydantic` to cast incoming function arguments to types according to their annotation.
```python
from pydantic import BaseModel
from propan import PropanApp, RabbitBroker
broker = RabbitBroker("amqp://guest:guest@localhost:5672/")
app = PropanApp(broker)
class SimpleMessage(BaseModel):
key: int
@broker.handle("test2")
async def second_handler(body: SimpleMessage):
assert isinstance(body.key, int)
```
---
## Dependencies
**Propan** a has dependencies management policy close to `pytest fixtures` and `FastAPI Depends` at the same time.
You can specify in functions arguments which dependencies
you would to use. Framework passes them from the global Context object.
Also, you can specify your own dependencies, call dependencies functions and
[more](https://github.com/Lancetnik/Propan/tree/main/examples/dependencies).
```python
from propan import PropanApp, RabbitBroker, Context, Depends
rabbit_broker = RabbitBroker("amqp://guest:guest@localhost:5672/")
app = PropanApp(rabbit_broker)
async def dependency(user_id: int) -> bool:
return True
@rabbit_broker.handle("test")
async def base_handler(user_id: int,
dep: bool = Depends(dependency),
broker: RabbitBroker = Context()):
assert dep is True
assert broker is rabbit_broker
```
---
## RPC over MQ
Also, **Propan** allows you to use **RPC** requests over your broker with a simple way:
```python
from propan import PropanApp, RabbitBroker
broker = RabbitBroker("amqp://guest:guest@localhost:5672/")
app = PropanApp(rabbit_broker)
@broker.handle("ping")
async def base_handler():
return "pong"
@app.after_startup
async def self_ping():
assert (
await broker.publish("", "ping", callback=True)
) == "pong"
```
---
## Project Documentation
**Propan** automatically generates documentation for your project according to the <a href="https://www.asyncapi.com/" target="_blank">**AsyncAPI**</a> specification. You can work with both generated artifacts and place a Web view of your documentation on resources available to related teams.
The availability of such documentation significantly simplifies the integration of services: you can immediately see what channels and message format the application works with. And most importantly, it doesn't cost you anything - **Propan** has already done everything for you!
---
## CLI power
**Propan** has its own CLI tool that provided the following features:
* project generation
* multiprocessing workers
* project hot reloading
* documentation generating and hosting
* custom command line arguments passing
### Context passing
For example: pass your current *.env* project setting to context
```bash
propan run serve:app --env=.env.dev
```
```python
from propan import PropanApp, RabbitBroker
from propan.annotations import ContextRepo
from pydantic_settings import BaseSettings
broker = RabbitBroker()
app = PropanApp(broker)
class Settings(BaseSettings):
url: str = "amqp://guest:guest@localhost:5672/"
@app.on_startup
async def setup(env: str, context: ContextRepo):
settings = Settings(_env_file=env)
await broker.connect(settings.url)
context.set_global("settings", settings)
```
### Project template
Also, **Propan CLI** is able to generate a production-ready application template:
```bash
propan create async rabbit [projectname]
```
*Notice: project template require* `pydantic[dotenv]` *installation.*
Run the created project:
```bash
# Run rabbimq first
docker compose --file [projectname]/docker-compose.yaml up -d
# Run project
propan run [projectname].app.serve:app --env=.env --reload
```
Now you can enjoy a new development experience!
---
## HTTP Frameworks integrations
### Any Framework
You can use **Propan** `MQBrokers` without `PropanApp`.
Just *start* and *stop* them according to your application lifespan.
```python
from propan import NatsBroker
from sanic import Sanic
app = Sanic("MyHelloWorldApp")
broker = NatsBroker("nats://localhost:4222")
@broker.handle("test")
async def base_handler(body):
print(body)
@app.after_server_start
async def start_broker(app, loop):
await broker.start()
@app.after_server_stop
async def stop_broker(app, loop):
await broker.close()
```
### FastAPI Plugin
Also, **Propan** can be used as part of **FastAPI**.
Just import a **PropanRouter** you need and declare the message handler
using the `@event` decorator. This decorator is similar to the decorator `@handle` for the corresponding brokers.
```python
from fastapi import Depends, FastAPI
from pydantic import BaseModel
from propan.fastapi import RabbitRouter
router = RabbitRouter("amqp://guest:guest@localhost:5672")
app = FastAPI(lifespan=router.lifespan_context)
class Incoming(BaseModel):
username: str
def call():
return True
@router.event("test")
async def hello(m: Incoming, d = Depends(call)):
return { "response": f"Hello, {m.username}!" }
app.include_router(router)
```
## Examples
To see more framework usages go to [**examples/**](https://github.com/Lancetnik/Propan/tree/main/examples)
## Contributors
Thanks for all of these amazing peoples made the project better!
<a href="https://github.com/Lancetnik/Propan/graphs/contributors">
<img src="https://contrib.rocks/image?repo=Lancetnik/Propan"/>
</a>
Raw data
{
"_id": null,
"home_page": "",
"name": "propan",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "framework,kafka,message brokers,nats,rabbitmq,redis,sqs",
"author": "",
"author_email": "Pastukhov Nikita <diementros@yandex.ru>",
"download_url": "https://files.pythonhosted.org/packages/0a/82/3072987bb1927b6b1437fec6de87821c345ddb4f5f7eb261cf116090cc8a/propan-0.1.5.26.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <a href=\"https://lancetnik.github.io/Propan/\" target=\"_blank\">\n <img src=\"https://lancetnik.github.io/Propan/assets/img/logo-no-background.png\" alt=\"Propan logo\" style=\"height: 250px; width: 600px;\"/>\n </a>\n</p>\n\n<p align=\"center\">\n <a href=\"https://github.com/Lancetnik/Propan/actions/workflows/tests.yml\" target=\"_blank\">\n <img src=\"https://github.com/Lancetnik/Propan/actions/workflows/tests.yml/badge.svg\" alt=\"Tests coverage\"/>\n </a>\n <a href=\"https://coverage-badge.samuelcolvin.workers.dev/redirect/lancetnik/propan\" target=\"_blank\">\n <img src=\"https://coverage-badge.samuelcolvin.workers.dev/lancetnik/propan.svg\" alt=\"Coverage\">\n </a>\n <a href=\"https://pypi.org/project/propan\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/v/propan?label=pypi%20package\" alt=\"Package version\">\n </a>\n <a href=\"https://pepy.tech/project/propan\" target=\"_blank\">\n <img src=\"https://static.pepy.tech/personalized-badge/propan?period=total&units=international_system&left_color=grey&right_color=blue&left_text=Downloads\" alt=\"downloads\"/>\n </a>\n <br/>\n <a href=\"https://pypi.org/project/propan\" target=\"_blank\">\n <img src=\"https://img.shields.io/pypi/pyversions/propan.svg\" alt=\"Supported Python versions\">\n </a>\n <a href=\"https://github.com/Lancetnik/Propan/blob/main/LICENSE\" target=\"_blank\">\n <img alt=\"GitHub\" src=\"https://img.shields.io/github/license/Lancetnik/Propan?color=%23007ec6\">\n </a>\n <a href=\"https://discord.gg/ChhMXJpvz7\" target=\"_blank\">\n <img alt=\"Discord\" src=\"https://img.shields.io/discord/1122560426794831872?logo=discord\">\n </a>\n</p>\n\n# Propan\n\n**Propan** - just *~~an another one HTTP~~* a **declarative Python Messaging Framework**. It's inspired by <a href=\"https://FastAPI.tiangolo.com/ru/\" target=\"_blank\">*FastAPI*</a> and <a href=\"https://docs.celeryq.dev/projects/kombu/en/stable/\" target=\"_blank\">*Kombu*</a>, simplify Message Brokers around code writing and provides a helpful development toolkit, which existed only in HTTP-frameworks world until now.\n\nIt's designed to create reactive microservices around <a href=\"https://microservices.io/patterns/communication-style/messaging.html\" target=\"_blank\">Messaging Architecture</a>.\n\nIt is a modern, high-level framework on top of popular specific Python brokers libraries, based on <a href=\"https://docs.pydantic.dev/\" target=\"_blank\">*pydantic*</a> and <a href=\"https://FastAPI.tiangolo.com/ru/\" target=\"_blank\">*FastAPI*</a>, <a href=\"https://docs.pytest.org/en/latest/\" target=\"_blank\">*pytest*</a> concepts.\n\n---\n\n## :warning::warning::warning: Deprecation notice :warning::warning::warning:\n\nThis project is superceeded by [**FastStream**](https://github.com/airtai/faststream).\n\n**FastStream** is a new package based on the ideas and experiences gained from [**FastKafka**](https://github.com/airtai/fastkafka) and **Propan**. By joining our forces, we picked up the best from both packages and created a unified way to write services capable of processing streamed data regardless of the underlying protocol.\n\nI\u2019ll continue to maintain **Propan** package, but new development will be in **FastStream**. If you are starting a new service, **FastStream** is the recommended way to do it.\n\nFor now **FastStream** supports **Kafka** and **RabbitMQ**. Other brokers support will be added in a few months.\n\nYou can find a detail migration guide in the [documentation](https://lancetnik.github.io/Propan/migration/)\n\n---\n\n**Documentation**: <a href=\"https://lancetnik.github.io/Propan/\" target=\"_blank\">https://lancetnik.github.io/Propan/</a>\n\n---\n\n### The key features are\n\n* **Simple**: Designed to be easy to use and learn.\n* **Intuitive**: Great editor support. Autocompletion everywhere.\n* [**Dependencies management**](#dependencies): Minimization of code duplication. Access to dependencies at any level of the call stack.\n* [**Integrations**](#http-frameworks-integrations): **Propan** is fully compatible with <a href=\"https://lancetnik.github.io/Propan/integrations/1_integrations-index/\" target=\"_blank\">any HTTP framework</a> you want\n* **MQ independent**: Single interface to popular MQ:\n * **Redis** (based on <a href=\"https://redis.readthedocs.io/en/stable/index.html\" target=\"_blank\">redis-py</a>)\n * **RabbitMQ** (based on <a href=\"https://aio-pika.readthedocs.io/en/latest/\" target=\"_blank\">aio-pika</a>)\n * **Kafka** (based on <a href=\"https://aiokafka.readthedocs.io/en/stable/\" target=\"_blank\">aiokafka</a>)\n * **SQS** (based on <a href=\"https://aiobotocore.readthedocs.io/en/latest/\" target=\"_blank\">aiobotocore</a>)\n * **Nats** (based on <a href=\"https://github.com/nats-io/nats.py\" target=\"_blank\">nats-py</a>)\n* <a href=\"https://lancetnik.github.io/Propan/getting_started/4_broker/6_rpc/\" target=\"_blank\">**RPC**</a>: The framework supports RPC requests over MQ, which will allow performing long operations on remote services asynchronously.\n* [**Great to develop**](#cli-power): CLI tool provides great development experience:\n * framework-independent way to manage the project environment\n * application code *hot reload*\n * robust application templates\n* [**Documentation**](#project-documentation): **Propan** automatically generates and presents an interactive <a href=\"https://www.asyncapi.com/\" target=\"_blank\">**AsyncAPI**</a> documentation for your project\n* <a href=\"https://lancetnik.github.io/Propan/getting_started/7_testing\" target=\"_blank\">**Testability**</a>: **Propan** allows you to test your app without external dependencies: you do not have to set up a Message Broker, you can use a virtual one!\n\n### Supported MQ brokers\n\n| | async | sync |\n|-------------------|:-------------------------------------------------------:|:-------------------------------------------:|\n| **RabbitMQ** | :heavy_check_mark: **stable** :heavy_check_mark: | :hammer_and_wrench: WIP :hammer_and_wrench: |\n| **Redis** | :heavy_check_mark: **stable** :heavy_check_mark: | :mag: planning :mag: |\n| **Nats** | :heavy_check_mark: **stable** :heavy_check_mark: | :mag: planning :mag: |\n| **Kafka** | :warning: **beta** :warning: | :mag: planning :mag: |\n| **SQS** | :warning: **beta** :warning: | :mag: planning :mag: |\n| **NatsJS** | :warning: **beta** :warning: | :mag: planning :mag: |\n| **ZeroMQ** | :hammer_and_wrench: WIP :hammer_and_wrench: | :mag: planning :mag: |\n| **MQTT** | :mag: planning :mag: | :mag: planning :mag: |\n| **Redis Streams** | :mag: planning :mag: | :mag: planning :mag: |\n| **Pulsar** | :mag: planning :mag: | :mag: planning :mag: |\n| **ActiveMQ** | :mag: planning :mag: | :mag: planning :mag: |\n| **AzureSB** | :mag: planning :mag: | :mag: planning :mag: |\n\n---\n\n### \u2b50 Support the project \u2b50\n\nIf you are interested in this project, please give me feedback by:\n\n- giving the [repository](https://github.com/Lancetnik/Propan) a star\n\n- tweet about <a href=\"https://twitter.com/compose/tweet?text=I'm like @PropanFramework because... https://github.com/Lancetnik/Propan\" class=\"external-link\" target=\"_blank\">**Propan**</a> and let me and others know why you use it\n\n- joining <a href=\"https://discord.gg/ChhMXJpvz7\" target=\"_blank\">Discord server</a>\n\nYour support helps me to stay in touch with you and encourages to\ncontinue developing and improving the library. Thank you for your\nsupport!\n\nReally, share information about this project with others. The bigger community we have - the better project will be!\n\n---\n\n## Declarative?\n\nWith declarative tools you can define **what you need to get**. With traditional imperative tools you must write **what you need to do**.\n\nTake a look at classic imperative tools, such as <a href=\"https://aio-pika.readthedocs.io/en/latest/\" target=\"_blank\">aio-pika</a>, <a href=\"https://pika.readthedocs.io/en/stable/\" target=\"_blank\">pika</a>, <a href=\"https://redis.readthedocs.io/en/stable/index.html\" target=\"_blank\">redis-py</a>, <a href=\"https://github.com/nats-io/nats.py\" target=\"_blank\">nats-py</a>, etc.\n\nThis is the **Quickstart** with the *aio-pika*:\n\n```python\nimport asyncio\nimport aio_pika\n\nasync def main():\n connection = await aio_pika.connect_robust(\n \"amqp://guest:guest@127.0.0.1/\"\n )\n\n queue_name = \"test_queue\"\n\n async with connection:\n channel = await connection.channel()\n\n queue = await channel.declare_queue(queue_name)\n\n async with queue.iterator() as queue_iter:\n async for message in queue_iter:\n async with message.process():\n print(message.body)\n\nasyncio.run(main())\n```\n\n**aio-pika** is a great tool with a really easy learning curve. But it's still imperative. You need to *connect*, declare *channel*, *queues*, *exchanges* by yourself. Also, you need to manage *connection*, *message*, *queue* context to avoid any troubles.\n\nIt is not a bad way, but it can be much easier.\n\n```python\nfrom propan import PropanApp, RabbitBroker\n\nbroker = RabbitBroker(\"amqp://guest:guest@localhost:5672/\")\napp = PropanApp(broker)\n\n@broker.handle(\"test_queue\")\nasync def base_handler(body):\n print(body)\n```\n\nThis is the **Propan** declarative way to write the same code. That is so much easier, isn't it?\n\n---\n\n## Quickstart\n\nInstall using `pip`:\n\n```shell\npip install \"propan[async-rabbit]\"\n# or\npip install \"propan[async-nats]\"\n# or\npip install \"propan[async-redis]\"\n# or\npip install \"propan[async-kafka]\"\n# or\npip install \"propan[async-sqs]\"\n```\n\n### Basic usage\n\nCreate an application with the following code at `serve.py`:\n\n```python\nfrom propan import PropanApp\nfrom propan import RabbitBroker\n# from propan import RedisBroker\n# from propan import NatsBroker\n# from propan import SQSBroker\n# from propan import KafkaBroker\n\nbroker = RabbitBroker(\"amqp://guest:guest@localhost:5672/\")\n# broker = NatsBroker(\"nats://localhost:4222\")\n# broker = RedisBroker(\"redis://localhost:6379\")\n# broker = SQSBroker(\"http://localhost:9324\", ...)\n# broker = KafkaBroker(\"localhost:9092\")\n\napp = PropanApp(broker)\n\n@broker.handle(\"test\")\nasync def base_handler(body):\n print(body)\n```\n\nAnd just run it:\n\n```shell\npropan run serve:app --workers 3\n```\n\n---\n\n## Type casting\n\nPropan uses `pydantic` to cast incoming function arguments to types according to their annotation.\n\n```python\nfrom pydantic import BaseModel\nfrom propan import PropanApp, RabbitBroker\n\nbroker = RabbitBroker(\"amqp://guest:guest@localhost:5672/\")\napp = PropanApp(broker)\n\nclass SimpleMessage(BaseModel):\n key: int\n\n@broker.handle(\"test2\")\nasync def second_handler(body: SimpleMessage):\n assert isinstance(body.key, int)\n\n```\n\n---\n\n## Dependencies\n\n**Propan** a has dependencies management policy close to `pytest fixtures` and `FastAPI Depends` at the same time.\nYou can specify in functions arguments which dependencies\nyou would to use. Framework passes them from the global Context object.\n\nAlso, you can specify your own dependencies, call dependencies functions and\n[more](https://github.com/Lancetnik/Propan/tree/main/examples/dependencies).\n\n```python\nfrom propan import PropanApp, RabbitBroker, Context, Depends\n\nrabbit_broker = RabbitBroker(\"amqp://guest:guest@localhost:5672/\")\napp = PropanApp(rabbit_broker)\n\nasync def dependency(user_id: int) -> bool:\n return True\n\n@rabbit_broker.handle(\"test\")\nasync def base_handler(user_id: int,\n dep: bool = Depends(dependency),\n broker: RabbitBroker = Context()):\n assert dep is True\n assert broker is rabbit_broker\n```\n\n---\n\n## RPC over MQ\n\nAlso, **Propan** allows you to use **RPC** requests over your broker with a simple way:\n\n```python\nfrom propan import PropanApp, RabbitBroker\n\nbroker = RabbitBroker(\"amqp://guest:guest@localhost:5672/\")\napp = PropanApp(rabbit_broker)\n\n@broker.handle(\"ping\")\nasync def base_handler():\n return \"pong\"\n\n@app.after_startup\nasync def self_ping():\n assert (\n await broker.publish(\"\", \"ping\", callback=True)\n ) == \"pong\"\n```\n\n---\n\n## Project Documentation\n\n**Propan** automatically generates documentation for your project according to the <a href=\"https://www.asyncapi.com/\" target=\"_blank\">**AsyncAPI**</a> specification. You can work with both generated artifacts and place a Web view of your documentation on resources available to related teams.\n\nThe availability of such documentation significantly simplifies the integration of services: you can immediately see what channels and message format the application works with. And most importantly, it doesn't cost you anything - **Propan** has already done everything for you!\n\n\n\n---\n\n## CLI power\n\n**Propan** has its own CLI tool that provided the following features:\n\n* project generation\n* multiprocessing workers\n* project hot reloading\n* documentation generating and hosting\n* custom command line arguments passing\n\n### Context passing\n\nFor example: pass your current *.env* project setting to context\n\n```bash\npropan run serve:app --env=.env.dev\n```\n\n```python\nfrom propan import PropanApp, RabbitBroker\nfrom propan.annotations import ContextRepo\nfrom pydantic_settings import BaseSettings\n\nbroker = RabbitBroker()\n\napp = PropanApp(broker)\n\nclass Settings(BaseSettings):\n url: str = \"amqp://guest:guest@localhost:5672/\"\n\n@app.on_startup\nasync def setup(env: str, context: ContextRepo):\n settings = Settings(_env_file=env)\n await broker.connect(settings.url)\n context.set_global(\"settings\", settings)\n```\n\n### Project template\n\nAlso, **Propan CLI** is able to generate a production-ready application template:\n\n```bash\npropan create async rabbit [projectname]\n```\n\n*Notice: project template require* `pydantic[dotenv]` *installation.*\n\nRun the created project:\n\n```bash\n# Run rabbimq first\ndocker compose --file [projectname]/docker-compose.yaml up -d\n\n# Run project\npropan run [projectname].app.serve:app --env=.env --reload\n```\n\nNow you can enjoy a new development experience!\n\n---\n\n## HTTP Frameworks integrations\n\n### Any Framework\n\nYou can use **Propan** `MQBrokers` without `PropanApp`.\nJust *start* and *stop* them according to your application lifespan.\n\n```python\nfrom propan import NatsBroker\nfrom sanic import Sanic\n\napp = Sanic(\"MyHelloWorldApp\")\nbroker = NatsBroker(\"nats://localhost:4222\")\n\n@broker.handle(\"test\")\nasync def base_handler(body):\n print(body)\n\n@app.after_server_start\nasync def start_broker(app, loop):\n await broker.start()\n\n@app.after_server_stop\nasync def stop_broker(app, loop):\n await broker.close()\n```\n\n### FastAPI Plugin\n\nAlso, **Propan** can be used as part of **FastAPI**.\n\nJust import a **PropanRouter** you need and declare the message handler\nusing the `@event` decorator. This decorator is similar to the decorator `@handle` for the corresponding brokers.\n\n```python\nfrom fastapi import Depends, FastAPI\nfrom pydantic import BaseModel\nfrom propan.fastapi import RabbitRouter\n\nrouter = RabbitRouter(\"amqp://guest:guest@localhost:5672\")\napp = FastAPI(lifespan=router.lifespan_context)\n\nclass Incoming(BaseModel):\n username: str\n\ndef call():\n return True\n\n@router.event(\"test\")\nasync def hello(m: Incoming, d = Depends(call)):\n return { \"response\": f\"Hello, {m.username}!\" }\n\napp.include_router(router)\n```\n\n## Examples\n\nTo see more framework usages go to [**examples/**](https://github.com/Lancetnik/Propan/tree/main/examples)\n\n## Contributors\n\nThanks for all of these amazing peoples made the project better!\n\n<a href=\"https://github.com/Lancetnik/Propan/graphs/contributors\">\n <img src=\"https://contrib.rocks/image?repo=Lancetnik/Propan\"/>\n</a>\n",
"bugtrack_url": null,
"license": "",
"summary": "Propan framework: the simplest way to work with a messaging queues",
"version": "0.1.5.26",
"project_urls": {
"Documentation": "https://lancetnik.github.io/Propan/",
"Homepage": "https://lancetnik.github.io/Propan/",
"Source": "https://github.com/Lancetnik/Propan",
"Tracker": "https://github.com/Lancetnik/Propan/issues"
},
"split_keywords": [
"framework",
"kafka",
"message brokers",
"nats",
"rabbitmq",
"redis",
"sqs"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "338b0a13202f0727a1ee25882266583fb2aea23c419aae4cbeb2d590656fb1cc",
"md5": "a8d8096c48d9260fa61b013a1ad8cd08",
"sha256": "b08aab5c7238833b7703374b990bfda1b86adaa21d6e30f816022171af5780f9"
},
"downloads": -1,
"filename": "propan-0.1.5.26-py3-none-any.whl",
"has_sig": false,
"md5_digest": "a8d8096c48d9260fa61b013a1ad8cd08",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 128783,
"upload_time": "2024-01-15T16:36:40",
"upload_time_iso_8601": "2024-01-15T16:36:40.994207Z",
"url": "https://files.pythonhosted.org/packages/33/8b/0a13202f0727a1ee25882266583fb2aea23c419aae4cbeb2d590656fb1cc/propan-0.1.5.26-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0a823072987bb1927b6b1437fec6de87821c345ddb4f5f7eb261cf116090cc8a",
"md5": "024172b97a860980d15821305b36bddc",
"sha256": "5d6d80b7328ad30cd3de8e15c035950c5b9c3e152a0980dd826054c95b6be1b3"
},
"downloads": -1,
"filename": "propan-0.1.5.26.tar.gz",
"has_sig": false,
"md5_digest": "024172b97a860980d15821305b36bddc",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 83313,
"upload_time": "2024-01-15T16:36:43",
"upload_time_iso_8601": "2024-01-15T16:36:43.691533Z",
"url": "https://files.pythonhosted.org/packages/0a/82/3072987bb1927b6b1437fec6de87821c345ddb4f5f7eb261cf116090cc8a/propan-0.1.5.26.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-01-15 16:36:43",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Lancetnik",
"github_project": "Propan",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"lcname": "propan"
}
