Add unit tests for QueueMessageTTLArguments to_argument() method; Upd…

…ate docstring.

src/omotes_sdk/internal/common/broker_interface.py

@@ -120,16 +120,20 @@ class QueueMessageTTLArguments():
     """Construct additional time-to-live arguments when declaring a queue."""
 
     queue_ttl: Optional[timedelta] = None
-    """Expires and deletes the queue after a period of inactivity.
-    The timedelta must be able to be casted into a positive integer."""
+    """Expires and deletes the queue after a period of time when it is not used.
+    The timedelta must be convertible into a positive integer.
+    Ref: https://www.rabbitmq.com/docs/ttl#queue-ttl"""
     message_ttl: Optional[timedelta] = None
     """Expires and deletes the message within the queue after the defined TTL.
-    The timedelta must be able to be casted into a non-negative integer."""
+    The timedelta must be convertible into a non-negative integer.
+    Ref: https://www.rabbitmq.com/docs/ttl#per-queue-message-ttl"""
     dead_letter_routing_key: Optional[str] = None
     """When specified, the expired message is republished to the designated dead letter queue.
-    If not set, the message's own routing key is used."""
+    If not set, the message's own routing key is used.
+    Ref: https://www.rabbitmq.com/docs/dlx#routing"""
     dead_letter_exchange: Optional[str] = None
-    """Dead letter exchange name."""
+    """Dead letter exchange name.
+    Ref: https://www.rabbitmq.com/docs/dlx"""
 
     def to_argument(self) -> Arguments:
         """Convert the time-to-live variables to the aio-pika `declare_queue` keyword arguments.

src/omotes_sdk/omotes_interface.py

@@ -197,7 +197,9 @@ def connect_to_submitted_job(
         :param auto_dead_letter_after_ttl: When erroneous situations occur (e.g. client is offline),
             the job result message (if available) will be dead lettered after the given TTL,
             and all queues of this job will be removed subsequently. Default to 48 hours if unset.
-            Set to `None` to turn off auto dead letter and clean up.
+            Set to `None` to turn off auto dead letter and clean up, but be aware this may lead to
+            messages and queues to be stored in RabbitMQ indefinitely
+            (which uses up memory & disk space).
         """
         if auto_disconnect_on_result:
             logger.info("Connecting to update for job %s with auto disconnect on result", job.id)
@@ -291,7 +293,9 @@ def submit_job(
         :param auto_dead_letter_after_ttl: When erroneous situations occur (e.g. client is offline),
             the job result message (if available) will be dead lettered after the given TTL,
             and all queues of this job will be removed subsequently. Default to 48 hours if unset.
-            Set to `None` to turn off auto dead letter and clean up.
+            Set to `None` to turn off auto dead letter and clean up, but be aware this may lead to
+            messages and queues to be stored in RabbitMQ indefinitely
+            (which uses up memory & disk space).
         :raises UnknownWorkflowException: If `workflow_type` is unknown as a possible workflow in
             this interface.
         :return: The job handle which is created. This object needs to be saved persistently by the

unit_test/internal/common/test_queue_message_ttl.py

@@ -0,0 +1,111 @@
+import unittest
+from datetime import timedelta
+from omotes_sdk.internal.common.broker_interface import QueueMessageTTLArguments
+
+
+class TestQueueMessageTTLArguments(unittest.TestCase):
+    def test__to_argument__no_arguments(self) -> None:
+        # Arrange / Act
+        args = QueueMessageTTLArguments()
+
+        # Assert
+        self.assertEqual(args.to_argument(), {})
+
+    def test__to_argument__queue_ttl(self) -> None:
+        # Arrange
+        q_ttl = timedelta(seconds=60)
+
+        # Act
+        args = QueueMessageTTLArguments(queue_ttl=q_ttl)
+
+        # Assert
+        self.assertEqual(args.to_argument(), {"x-expires": 60000})
+
+    def test__to_argument__negative_queue_ttl(self) -> None:
+        # Arrange
+        q_ttl = timedelta(seconds=-60)
+
+        # Act / Assert
+        with self.assertRaises(ValueError):
+            QueueMessageTTLArguments(queue_ttl=q_ttl).to_argument()
+
+    def test__to_argument__zero_queue_ttl(self) -> None:
+        # Arrange
+        q_ttl = timedelta(seconds=0)
+
+        # Act / Assert
+        with self.assertRaises(ValueError):
+            QueueMessageTTLArguments(queue_ttl=q_ttl).to_argument()
+
+    def test__to_argument__message_ttl(self) -> None:
+        # Arrange
+        msg_ttl = timedelta(seconds=30)
+
+        # Act
+        args = QueueMessageTTLArguments(message_ttl=msg_ttl)
+
+        # Assert
+        self.assertEqual(args.to_argument(), {"x-message-ttl": 30000})
+
+    def test__to_argument__negative_message_ttl(self) -> None:
+        # Arrange
+        msg_ttl = timedelta(seconds=-30)
+
+        # Act / Assert
+        with self.assertRaises(ValueError):
+            QueueMessageTTLArguments(message_ttl=msg_ttl).to_argument()
+
+    def test__to_argument__message_ttl_larger_than_queue_ttl(self) -> None:
+        # Arrange
+        q_ttl = timedelta(seconds=30)
+        msg_ttl = timedelta(seconds=60)
+
+        # Act / Assert
+        with self.assertRaises(ValueError):
+            QueueMessageTTLArguments(
+                queue_ttl=q_ttl,
+                message_ttl=msg_ttl
+            ).to_argument()
+
+    def test__to_argument__dead_letter_routing_key(self) -> None:
+        # Arrange
+        dl_routing_key = "test-dlq"
+
+        # Act
+        args = QueueMessageTTLArguments(dead_letter_routing_key=dl_routing_key)
+
+        # Assert
+        self.assertEqual(args.to_argument(), {"x-dead-letter-routing-key": "test-dlq"})
+
+    def test__to_argument__dead_letter_exchange(self) -> None:
+        # Arrange
+        dl_exchange = "test-exchange"
+
+        # Act
+        args = QueueMessageTTLArguments(dead_letter_exchange=dl_exchange)
+
+        # Assert
+        self.assertEqual(args.to_argument(), {"x-dead-letter-exchange": "test-exchange"})
+
+    def test__to_argument__all_arguments(self) -> None:
+        # Arrange
+        q_ttl = timedelta(minutes=2)
+        msg_ttl = timedelta(minutes=1)
+        dl_routing_key = "test-dlq"
+        dl_exchange = "test-exchange"
+
+        # Act
+        args = QueueMessageTTLArguments(
+            queue_ttl=q_ttl,
+            message_ttl=msg_ttl,
+            dead_letter_routing_key=dl_routing_key,
+            dead_letter_exchange=dl_exchange
+        )
+
+        # Assert
+        self.assertEqual(args.to_argument(), {
+            "x-expires": 120000,
+            "x-message-ttl": 60000,
+            "x-dead-letter-routing-key": "test-dlq",
+            "x-dead-letter-exchange": "test-exchange"
+        })