Change the class name for the consumer

add documentation

Signed-off-by: Gabriele Santomaggio <[email protected]>

Author: Gsantomaggio

examples/getting_started/main.py

@@ -5,15 +5,15 @@
     AddressHelper,
     BindingSpecification,
     Connection,
-    DeliveryConsumerHandler,
+    AMQPMessagingHandler,
     Event,
     ExchangeSpecification,
     Message,
     QuorumQueueSpecification,
 )
 
 
-class MyMessageHandler(DeliveryConsumerHandler):
+class MyMessageHandler(AMQPMessagingHandler):
 
     def __init__(self):
         super().__init__()

rabbitmq_amqp_python_client/__init__.py

@@ -4,8 +4,8 @@
 from .common import ExchangeType, QueueType
 from .connection import Connection
 from .consumer import Consumer
-from .delivery_consumer_handler import (
-    DeliveryConsumerHandler,
+from .amqp_consumer_handler import (
+    AMQPMessagingHandler,
 )
 from .entities import (
     BindingSpecification,
@@ -51,5 +51,5 @@
     "symbol",
     "ExchangeType",
     "AddressHelper",
-    "DeliveryConsumerHandler",
+    "AMQPMessagingHandler",
 ]

rabbitmq_amqp_python_client/amqp_consumer_handler.py

@@ -0,0 +1,23 @@
+from .delivery_context import DeliveryContext
+from .qpid.proton.handlers import MessagingHandler
+
+
+''' 
+AMQPMessagingHandler extends the QPID MessagingHandler. 
+It is an helper to set the default values needed for manually accepting and settling messages.
+
+self.delivery_context is an instance of DeliveryContext, which is used to accept, reject, 
+requeue or requeue with annotations a message.
+
+It is not mandatory to use this class, but it is a good practice to use it. 
+'''
+class AMQPMessagingHandler(MessagingHandler):  # type: ignore
+
+    def __init__(self, auto_accept: bool = False, auto_settle: bool = True):
+        """
+        :param auto_accept: if True, the message is automatically accepted
+        by default is false, so the user has to manually accept the message and decide with the
+        different methods of the delivery_context what to do with the message
+        """
+        super().__init__(auto_accept=auto_accept, auto_settle=auto_settle)
+        self.delivery_context: DeliveryContext = DeliveryContext()

rabbitmq_amqp_python_client/delivery_consumer_handler.py

@@ -4,21 +4,54 @@
 from .qpid.proton._delivery import Delivery
 from .qpid.proton._events import Event
 
+'''
+DeliveryContext is a class that is used to accept, reject, requeue or requeue with annotations a message.
+It is an helper to set the default values needed for manually accepting and settling messages.
+'''
+
 
 class DeliveryContext:
+    """
+    Accept the message (AMQP 1.0 <code>accepted</code> outcome).
+
+    This means the message has been processed and the broker can delete it.
+    """
 
     def accept(self, event: Event) -> None:
         dlv = event.delivery
         dlv.update(Delivery.ACCEPTED)
         dlv.settle()
 
+    """
+    Reject the message (AMQP 1.0 <code>rejected</code> outcome).
+    This means the message cannot be processed because it is invalid, the broker can drop it
+    or dead-letter it if it is configured.
+    """
+
     def discard(self, event: Event) -> None:
         dlv = event.delivery
         dlv.update(Delivery.REJECTED)
         dlv.settle()
 
+    """
+    Discard the message with annotations to combine with the existing message annotations.
+    This means the message cannot be processed because it is invalid, the broker can drop it
+    or dead-letter it if it is configured.
+    Application-specific annotation keys must start with the <code>x-opt-</code> prefix.
+    Annotation keys the broker understands starts with <code>x-</code>, but not with <code>x-opt-
+    
+        This maps to the AMQP 1.0 
+        modified{delivery-failed = true, undeliverable-here = true}</code> outcome.
+         <param name="annotations"> annotations message annotations to combine with existing ones </param>
+        <a
+            href="https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-modified">AMQP
+            1.0 <code>modified</code> outcome</a>
+        
+         The annotations can be used only with Quorum queues, see https://www.rabbitmq.com/docs/amqp#modified-outcome
+    """
+
     def discard_with_annotations(
-        self, event: Event, annotations: Dict[str, "PythonAMQPData"]
+            self, event: Event, annotations: Dict[str, "PythonAMQPData"]
     ) -> None:
         dlv = event.delivery
         dlv.local.annotations = annotations
@@ -28,13 +61,39 @@ def discard_with_annotations(
         dlv.update(Delivery.MODIFIED)
         dlv.settle()
 
+    """
+    Requeue the message (AMQP 1.0 <code>released</code> outcome).   
+    This means the message has not been processed and the broker can requeue it and deliver it
+    to the same or a different consumer.    
+    """
+
     def requeue(self, event: Event) -> None:
         dlv = event.delivery
         dlv.update(Delivery.RELEASED)
         dlv.settle()
 
+    """
+     Requeue the message with annotations to combine with the existing message annotations.
+         
+        This means the message has not been processed and the broker can requeue it and deliver it
+         to the same or a different consumer.
+         Application-specific annotation keys must start with the <code>x-opt-</code> prefix.
+         Annotation keys the broker understands starts with <code>x-</code>, but not with <code>x-opt-
+         </code>.
+        
+         This maps to the AMQP 1.0 <code>
+         modified{delivery-failed = false, undeliverable-here = false}</code> outcome.
+        
+         <param name="annotations"> annotations message annotations to combine with existing ones </param>
+        <a
+             href="https://docs.oasis-open.org/amqp/core/v1.0/os/amqp-core-messaging-v1.0-os.html#type-modified">AMQP
+             1.0 <code>modified</code> outcome</a>
+        
+        The annotations can be used only with Quorum queues, see https://www.rabbitmq.com/docs/amqp#modified-outcome
+    """
+
     def requeue_with_annotations(
-        self, event: Event, annotations: Dict[str, "PythonAMQPData"]
+            self, event: Event, annotations: Dict[str, "PythonAMQPData"]
     ) -> None:
         dlv = event.delivery
         dlv.local.annotations = annotations

rabbitmq_amqp_python_client/delivery_context.py

@@ -3,7 +3,7 @@
 from rabbitmq_amqp_python_client import (
     AddressHelper,
     Connection,
-    DeliveryConsumerHandler,
+    AMQPMessagingHandler,
     Event,
     symbol,
 )
@@ -57,7 +57,7 @@ def __str__(self) -> str:
         return repr(self.msg)
 
 
-class MyMessageHandlerAccept(DeliveryConsumerHandler):
+class MyMessageHandlerAccept(AMQPMessagingHandler):
 
     def __init__(self):
         super().__init__()
@@ -71,7 +71,7 @@ def on_message(self, event: Event):
             raise ConsumerTestException("consumed")
 
 
-class MyMessageHandlerNoack(DeliveryConsumerHandler):
+class MyMessageHandlerNoack(AMQPMessagingHandler):
 
     def __init__(self):
         super().__init__(auto_settle=False)
@@ -86,7 +86,7 @@ def on_message(self, event: Event):
             raise ConsumerTestException("consumed")
 
 
-class MyMessageHandlerDiscard(DeliveryConsumerHandler):
+class MyMessageHandlerDiscard(AMQPMessagingHandler):
 
     def __init__(self):
         super().__init__()
@@ -100,7 +100,7 @@ def on_message(self, event: Event):
             raise ConsumerTestException("consumed")
 
 
-class MyMessageHandlerDiscardWithAnnotations(DeliveryConsumerHandler):
+class MyMessageHandlerDiscardWithAnnotations(AMQPMessagingHandler):
 
     def __init__(self):
         super().__init__()
@@ -116,7 +116,7 @@ def on_message(self, event: Event):
             raise ConsumerTestException("consumed")
 
 
-class MyMessageHandlerRequeue(DeliveryConsumerHandler):
+class MyMessageHandlerRequeue(AMQPMessagingHandler):
 
     def __init__(self):
         super().__init__()
@@ -130,7 +130,7 @@ def on_message(self, event: Event):
             raise ConsumerTestException("consumed")
 
 
-class MyMessageHandlerRequeueWithAnnotations(DeliveryConsumerHandler):
+class MyMessageHandlerRequeueWithAnnotations(AMQPMessagingHandler):
 
     def __init__(self):
         super().__init__()