(docs) update comments, readme, add examples

Author: trowinshade

README.md

@@ -1,8 +1,27 @@
 # aiocarrot
 
-**aiocarrot** is fully asynchronous framework for working with <a href="https://www.rabbitmq.com/">RabbitMQ</a>
+**aiocarrot** is a fully asynchronous framework for working with the <a href="https://www.rabbitmq.com/">RabbitMQ</a> message broker
 
-Accelerate development with a message broker at times with **aiocarrot**
+___
+
+**Source Code: https://github.com/d3nbr0/aiocarrot**
+
+___
+
+The key features are:
+
+* **Completely asynchronous** - aiocarrot has the <a href="https://pypi.org/project/aio-pika/">aiopika</a> library running under the hood
+* **Fast to code** - the framework allows you to reduce the amount of code in your project, as well as speed up its development
+* **Fields validation** - aiocarrot supports field validation using <a href="https://pypi.org/project/pydantic/">pydantic</a>
+
+## Requirements
+
+The following dependencies are required for **aiocarrot** to work:
+
+* <a href="https://pypi.org/project/aio-pika/">aio-pika</a> for working with RabbitMQ
+* <a href="https://pypi.org/project/pydantic/">pydantic</a> for fields validation
+* <a href="https://pypi.org/project/ujson/">ujson</a> for sending and receiving messages
+* <a href="https://pypi.org/project/loguru/">loguru</a> for logging :)
 
 ## Installation
 
@@ -68,4 +87,6 @@ if __name__ == '__main__':
     asyncio.run(main())
 ```
 
+**You can find more examples <a href="https://github.com/d3nbr0/aiocarrot/tree/main/examples">here</a>**
+
 It's very simple to use. Enjoy!

aiocarrot/__meta__.py

@@ -1 +1 @@
-__version__ = '1.0.0'
+__version__ = '1.0.1'

aiocarrot/carrot.py

@@ -34,10 +34,10 @@ def __init__(self, url: str, queue_name: str) -> None:
 
     async def send(self, _cnm: str, **kwargs) -> 'ConfirmationFrameType':
         """
-        Send message with specified name
+        Send a message with the specified type and the specified payload
 
-        :param _cnm: Message name
-        :param kwargs: Message payload
+        :param _cnm: The name of the message (used to determine the type of message being sent)
+        :param kwargs: The payload transmitted in the message body
         :return:
         """
 
@@ -69,7 +69,7 @@ def setup_consumer(self, consumer: 'Consumer') -> None:
 
     async def run(self) -> None:
         """
-        Start carrot listening
+        Starts the main loop of the Carrot new message listener
 
         :return:
         """
@@ -100,7 +100,7 @@ async def run(self) -> None:
 
     async def _consumer_loop(self) -> None:
         """
-        Consumer primary loop
+        The main event loop used by Carrot to receive new messages and pass them on to the handler
 
         :return:
         """
@@ -161,7 +161,7 @@ async def _consumer_loop(self) -> None:
 
     async def _get_queue(self) -> 'aio_pika.abc.AbstractQueue':
         """
-        Get active broker queue
+        Retrieves the currently active aiopika queue object
 
         :return: aiopika queue
         """
@@ -174,7 +174,7 @@ async def _get_queue(self) -> 'aio_pika.abc.AbstractQueue':
 
     async def _get_channel(self) -> 'aio_pika.abc.AbstractChannel':
         """
-        Get active broker channel
+        Gets the current active object of the aiopika channel
 
         :return: aiopika channel
         """
@@ -187,7 +187,7 @@ async def _get_channel(self) -> 'aio_pika.abc.AbstractChannel':
 
     async def _get_connection(self) -> 'aio_pika.abc.AbstractConnection':
         """
-        Get active connection to the broker
+        Retrieves the object of an active connection with the broker using aiopika
 
         :return: aiopika broker connection
         """

examples/01_consumer.py

@@ -0,0 +1,60 @@
+# This is an example of a consumer whose task is to create new users and add points to their balance
+#
+# In a real project, you can use your own database instead of a dictionary.
+# For example, you can use SQLAlchemy ORM to work with SQL databases.
+
+
+from aiocarrot import Carrot, Consumer
+
+
+consumer = Consumer()
+users: dict[int, int] = {}
+
+
+@consumer.message(name='register_user')
+async def register_user_message(user_id: int) -> None:
+    """
+    Example of a message handler for registering a new user
+
+    :param user_id: User identifier (this field is required and must be of the int type)
+    :return:
+    """
+
+    if user_id in users:
+        raise ValueError('This user is already registered')
+
+    users[user_id] = 0
+
+
+@consumer.message(name='add_points')
+async def add_points_message(user_id: int, amount: int = None) -> None:
+    """
+    Adds the number of points to the user
+
+    :param user_id: User identifier
+    :param amount: The number of points to be added
+    :return:
+    """
+
+    if user_id not in users:
+        raise ValueError('This user is not registered')
+
+    if amount is None:
+        amount = 100
+
+    users[user_id] += amount
+
+
+async def main() -> None:
+    """ Entrypoint of example application """
+
+    carrot = Carrot(url='amqp://guest:guest@localhost:5672/', queue_name='users')
+    carrot.setup_consumer(consumer)
+
+    await carrot.run()
+
+
+if __name__ == '__main__':
+    import asyncio
+
+    asyncio.run(main())

examples/02_publisher.py

@@ -0,0 +1,21 @@
+# In this example, we are sending messages so that the code from the first example can process them
+
+from aiocarrot import Carrot
+
+
+async def main() -> None:
+    """ Entrypoint of example application """
+
+    carrot = Carrot(url='amqp://guest:guest@localhost:5672/', queue_name='users')
+
+    await carrot.send('register_user', user_id=1)
+    await carrot.send('add_points', user_id=1, amount=1000)
+    await carrot.send('add_points', user_id=1)
+
+    # If you look at the example 01_consumer.py then you will see that the amount argument
+    # is optional and by default the user is awarded 100 points
+
+if __name__ == '__main__':
+    import asyncio
+
+    asyncio.run(main())

examples/03_fastapi.py

@@ -0,0 +1,30 @@
+# This example shows an example of the code for sending data to a queue using FastAPI
+
+
+from fastapi import FastAPI, Body
+from aiocarrot import Carrot
+
+
+app = FastAPI()
+carrot = Carrot(url='amqp://guest:guest@localhost:5672/', queue_name='users')
+
+
+@app.post('/signup')
+async def register_user_view(user_id: int = Body(embed=True)):
+    """ An example of an API method for creating a new user """
+
+    await carrot.send('register_user', user_id=user_id)
+
+    return {'status': True}
+
+
+@app.post('/reward')
+async def reward_view(user_id: int = Body(embed=True), amount: int = Body(embed=True)):
+    """
+    An example of an API method for receiving a reward in
+    the amount of the number of points passed in the request
+    """
+
+    await carrot.send('add_points', user_id=user_id, amount=amount)
+
+    return {'status': True}