jararaca 0.3.11a16__py3-none-any.whl → 0.4.0a19__py3-none-any.whl

jararaca/utils/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later

jararaca/utils/env_parse_utils.py

@@ -0,0 +1,133 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import os
+from typing import Literal, Optional, TypeVar, overload
+
+
+def is_env_truffy(var_name: str) -> bool:
+    value = os.getenv(var_name, "").lower()
+    return value in ("1", "true", "yes", "on")
+
+
+DF_BOOL_T = TypeVar("DF_BOOL_T", bound="bool")
+
+
+@overload
+def get_env_bool(
+    var_name: str, default: DF_BOOL_T
+) -> DF_BOOL_T | bool | Literal["invalid"]: ...
+
+
+@overload
+def get_env_bool(
+    var_name: str, default: None = None
+) -> bool | None | Literal["invalid"]: ...
+
+
+def get_env_bool(
+    var_name: str, default: DF_BOOL_T | None = None
+) -> DF_BOOL_T | bool | Literal["invalid"] | None:
+    value = os.getenv(var_name)
+    if value is None:
+        return default
+    value_lower = value.lower()
+    if value_lower in ("1", "true", "yes", "on"):
+        return True
+    elif value_lower in ("0", "false", "no", "off"):
+        return False
+    else:
+        return "invalid"
+
+
+DF_INT_T = TypeVar("DF_INT_T", bound="int | None | Literal[False]")
+
+
+@overload
+def get_env_int(var_name: str, default: None = None) -> int | None | Literal[False]: ...
+
+
+@overload
+def get_env_int(
+    var_name: str, default: DF_INT_T
+) -> DF_INT_T | int | Literal[False]: ...
+
+
+def get_env_int(
+    var_name: str, default: DF_INT_T = False  # type: ignore[assignment]
+) -> DF_INT_T | int | Literal[False]:
+    value = os.getenv(var_name)
+    if value is None:
+        return default
+    try:
+        return int(value)
+    except ValueError:
+        return False
+
+
+DF_FLOAT_T = TypeVar("DF_FLOAT_T", bound="float | None | Literal[False]")
+
+
+@overload
+def get_env_float(
+    var_name: str, default: None = None
+) -> float | None | Literal[False]: ...
+
+
+@overload
+def get_env_float(
+    var_name: str, default: DF_FLOAT_T
+) -> DF_FLOAT_T | float | Literal[False]: ...
+
+
+def get_env_float(
+    var_name: str, default: DF_FLOAT_T = False  # type: ignore[assignment]
+) -> DF_FLOAT_T | float | Literal[False]:
+    value = os.getenv(var_name)
+    if value is None:
+        return default
+    try:
+        return float(value)
+    except ValueError:
+        return False
+
+
+DF_STR_T = TypeVar("DF_STR_T", bound="Optional[str]")
+
+
+@overload
+def get_env_str(var_name: str, default: None = None) -> str | None: ...
+
+
+@overload
+def get_env_str(var_name: str, default: DF_STR_T) -> DF_STR_T | str: ...
+
+
+def get_env_str(var_name: str, default: DF_STR_T = None) -> DF_STR_T | str:  # type: ignore[assignment]
+    value = os.getenv(var_name)
+    if value is None:
+        return default
+    return value
+
+
+def get_env_list(var_name: str, separator: str = ",") -> list[str]:
+    value = os.getenv(var_name, "")
+    if not value:
+        return []
+    return [item.strip() for item in value.split(separator) if item.strip()]
+
+
+def get_env_dict(
+    var_name: str, item_separator: str = ",", key_value_separator: str = "="
+) -> dict[str, str]:
+    value = os.getenv(var_name, "")
+    result: dict[str, str] = {}
+    if not value:
+        return result
+    items = [item.strip() for item in value.split(item_separator) if item.strip()]
+    for item in items:
+        if key_value_separator in item:
+            key, val = item.split(key_value_separator, 1)
+            result[key.strip()] = val.strip()
+    return result

jararaca/utils/rabbitmq_utils.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 import logging
 
 from aio_pika.abc import AbstractChannel, AbstractExchange, AbstractQueue
@@ -27,20 +31,24 @@ class RabbitmqUtils:
             )
         except ChannelNotFoundEntity as e:
             logger.error(
-                f"Dead Letter Exchange '{cls.DEAD_LETTER_EXCHANGE}' does not exist. "
-                f"Please use the declare command to create it first. Error: {e}"
+                "Dead Letter Exchange '%s' does not exist. "
+                "Please use the declare command to create it first. Error: %s",
+                cls.DEAD_LETTER_EXCHANGE,
+                e,
             )
             raise
         except ChannelClosed as e:
             logger.error(
-                f"Channel closed while getting Dead Letter Exchange '{cls.DEAD_LETTER_EXCHANGE}'. "
-                f"Error: {e}"
+                "Channel closed while getting Dead Letter Exchange '%s'. " "Error: %s",
+                cls.DEAD_LETTER_EXCHANGE,
+                e,
             )
             raise
         except AMQPError as e:
             logger.error(
-                f"AMQP error while getting Dead Letter Exchange '{cls.DEAD_LETTER_EXCHANGE}'. "
-                f"Error: {e}"
+                "AMQP error while getting Dead Letter Exchange '%s'. " "Error: %s",
+                cls.DEAD_LETTER_EXCHANGE,
+                e,
             )
             raise
 
@@ -71,20 +79,24 @@ class RabbitmqUtils:
             )
         except ChannelNotFoundEntity as e:
             logger.error(
-                f"Dead Letter Queue '{cls.DEAD_LETTER_QUEUE}' does not exist. "
-                f"Please use the declare command to create it first. Error: {e}"
+                "Dead Letter Queue '%s' does not exist. "
+                "Please use the declare command to create it first. Error: %s",
+                cls.DEAD_LETTER_QUEUE,
+                e,
             )
             raise
         except ChannelClosed as e:
             logger.error(
-                f"Channel closed while getting Dead Letter Queue '{cls.DEAD_LETTER_QUEUE}'. "
-                f"Error: {e}"
+                "Channel closed while getting Dead Letter Queue '%s'. " "Error: %s",
+                cls.DEAD_LETTER_QUEUE,
+                e,
             )
             raise
         except AMQPError as e:
             logger.error(
-                f"AMQP error while getting Dead Letter Queue '{cls.DEAD_LETTER_QUEUE}'. "
-                f"Error: {e}"
+                "AMQP error while getting Dead Letter Queue '%s'. " "Error: %s",
+                cls.DEAD_LETTER_QUEUE,
+                e,
             )
             raise
 
@@ -120,19 +132,20 @@ class RabbitmqUtils:
             return dlx, dlq
         except ChannelNotFoundEntity as e:
             logger.error(
-                f"Dead Letter infrastructure does not exist completely. "
-                f"Please use the declare command to create it first. Error: {e}"
+                "Dead Letter infrastructure does not exist completely. "
+                "Please use the declare command to create it first. Error: %s",
+                e,
             )
             raise
         except ChannelClosed as e:
             logger.error(
-                f"Channel closed while getting Dead Letter infrastructure. "
-                f"Error: {e}"
+                "Channel closed while getting Dead Letter infrastructure. " "Error: %s",
+                e,
             )
             raise
         except AMQPError as e:
             logger.error(
-                f"AMQP error while getting Dead Letter infrastructure. " f"Error: {e}"
+                "AMQP error while getting Dead Letter infrastructure. " "Error: %s", e
             )
             raise
 
@@ -161,19 +174,22 @@ class RabbitmqUtils:
             return await channel.get_exchange(exchange_name)
         except ChannelNotFoundEntity as e:
             logger.error(
-                f"Exchange '{exchange_name}' does not exist. "
-                f"Please use the declare command to create it first. Error: {e}"
+                "Exchange '%s' does not exist. "
+                "Please use the declare command to create it first. Error: %s",
+                exchange_name,
+                e,
             )
             raise
         except ChannelClosed as e:
             logger.error(
-                f"Channel closed while getting exchange '{exchange_name}'. "
-                f"Error: {e}"
+                "Channel closed while getting exchange '%s'. " "Error: %s",
+                exchange_name,
+                e,
             )
             raise
         except AMQPError as e:
             logger.error(
-                f"AMQP error while getting exchange '{exchange_name}'. " f"Error: {e}"
+                "AMQP error while getting exchange '%s'. " "Error: %s", exchange_name, e
             )
             raise
 
@@ -206,18 +222,20 @@ class RabbitmqUtils:
             return await channel.get_queue(queue_name)
         except ChannelNotFoundEntity as e:
             logger.error(
-                f"Queue '{queue_name}' does not exist. "
-                f"Please use the declare command to create it first. Error: {e}"
+                "Queue '%s' does not exist. "
+                "Please use the declare command to create it first. Error: %s",
+                queue_name,
+                e,
             )
             raise
         except ChannelClosed as e:
             logger.error(
-                f"Channel closed while getting queue '{queue_name}'. " f"Error: {e}"
+                "Channel closed while getting queue '%s'. " "Error: %s", queue_name, e
             )
             raise
         except AMQPError as e:
             logger.error(
-                f"AMQP error while getting queue '{queue_name}'. " f"Error: {e}"
+                "AMQP error while getting queue '%s'. " "Error: %s", queue_name, e
             )
             raise
 
@@ -255,20 +273,24 @@ class RabbitmqUtils:
             return await channel.get_queue(queue_name)
         except ChannelNotFoundEntity as e:
             logger.error(
-                f"Scheduler queue '{queue_name}' does not exist. "
-                f"Please use the declare command to create it first. Error: {e}"
+                "Scheduler queue '%s' does not exist. "
+                "Please use the declare command to create it first. Error: %s",
+                queue_name,
+                e,
             )
             raise
         except ChannelClosed as e:
             logger.error(
-                f"Channel closed while getting scheduler queue '{queue_name}'. "
-                f"Error: {e}"
+                "Channel closed while getting scheduler queue '%s'. " "Error: %s",
+                queue_name,
+                e,
             )
             raise
         except AMQPError as e:
             logger.error(
-                f"AMQP error while getting scheduler queue '{queue_name}'. "
-                f"Error: {e}"
+                "AMQP error while getting scheduler queue '%s'. " "Error: %s",
+                queue_name,
+                e,
             )
             raise
 
@@ -310,15 +332,17 @@ class RabbitmqUtils:
             )
         except ChannelNotFoundEntity:
             # Exchange might not exist, which is fine
-            logger.info(
-                f"Exchange '{exchange_name}' does not exist, nothing to delete."
+            logger.debug(
+                "Exchange '%s' does not exist, nothing to delete.", exchange_name
             )
         except ChannelClosed as e:
             logger.warning(
-                f"Channel closed while deleting exchange '{exchange_name}': {e}"
+                "Channel closed while deleting exchange '%s': %s", exchange_name, e
             )
         except AMQPError as e:
-            logger.warning(f"AMQP error while deleting exchange '{exchange_name}': {e}")
+            logger.warning(
+                "AMQP error while deleting exchange '%s': %s", exchange_name, e
+            )
 
     @classmethod
     async def delete_queue(
@@ -339,8 +363,57 @@ class RabbitmqUtils:
             )
         except ChannelNotFoundEntity:
             # Queue might not exist, which is fine
-            logger.info(f"Queue '{queue_name}' does not exist, nothing to delete.")
+            logger.debug("Queue '%s' does not exist, nothing to delete.", queue_name)
+        except ChannelClosed as e:
+            logger.warning(
+                "Channel closed while deleting queue '%s': %s", queue_name, e
+            )
+        except AMQPError as e:
+            logger.warning("AMQP error while deleting queue '%s': %s", queue_name, e)
+
+    @classmethod
+    async def get_dl_queue_message_count(cls, channel: AbstractChannel) -> int:
+        """
+        Get the message count in the Dead Letter Queue.
+        Returns 0 if the queue doesn't exist.
+        """
+        try:
+            await channel.get_queue(cls.DEAD_LETTER_QUEUE)
+            # The declaration property contains the message count
+            queue_info = await channel.declare_queue(
+                cls.DEAD_LETTER_QUEUE, passive=True
+            )
+            return queue_info.declaration_result.message_count or 0
+        except ChannelNotFoundEntity:
+            logger.debug("Dead Letter Queue does not exist.")
+            return 0
+        except ChannelClosed as e:
+            logger.error("Channel closed while getting DLQ message count: %s", e)
+            raise
+        except AMQPError as e:
+            logger.error("AMQP error while getting DLQ message count: %s", e)
+            raise
+
+    @classmethod
+    async def purge_dl_queue(cls, channel: AbstractChannel) -> int:
+        """
+        Purge all messages from the Dead Letter Queue.
+        Returns the number of messages purged.
+        """
+        try:
+            queue = await channel.get_queue(cls.DEAD_LETTER_QUEUE)
+            result = await queue.purge()
+            return result.message_count or 0
+        except ChannelNotFoundEntity as e:
+            logger.error(
+                "Dead Letter Queue '%s' does not exist. Error: %s",
+                cls.DEAD_LETTER_QUEUE,
+                e,
+            )
+            raise
         except ChannelClosed as e:
-            logger.warning(f"Channel closed while deleting queue '{queue_name}': {e}")
+            logger.error("Channel closed while purging Dead Letter Queue: %s", e)
+            raise
         except AMQPError as e:
-            logger.warning(f"AMQP error while deleting queue '{queue_name}': {e}")
+            logger.error("AMQP error while purging Dead Letter Queue: %s", e)
+            raise

jararaca/utils/retry.py

@@ -1,3 +1,7 @@
+# SPDX-FileCopyrightText: 2025 Lucas S
+#
+# SPDX-License-Identifier: GPL-3.0-or-later
+
 import asyncio
 import logging
 import random
@@ -10,7 +14,7 @@ P = ParamSpec("P")
 T = TypeVar("T")
 
 
-class RetryConfig:
+class RetryPolicy:
     """Configuration for the retry mechanism."""
 
     def __init__(
@@ -45,7 +49,7 @@ async def retry_with_backoff(
     fn: Callable[[], Awaitable[T]],
     # args: P.args,
     # kwargs: P.kwargs,
-    retry_config: Optional[RetryConfig] = None,
+    retry_policy: RetryPolicy,
     on_retry_callback: Optional[Callable[[int, E, float], None]] = None,
     retry_exceptions: tuple[type[E], ...] = (),
 ) -> T:
@@ -66,38 +70,39 @@ async def retry_with_backoff(
     Raises:
         The last exception encountered if all retries fail
     """
-    if retry_config is None:
-        retry_config = RetryConfig()
 
     last_exception = None
-    delay = retry_config.initial_delay
+    delay = retry_policy.initial_delay
 
-    for retry_count in range(retry_config.max_retries + 1):
+    for retry_count in range(retry_policy.max_retries + 1):
         try:
             return await fn()
         except retry_exceptions as e:
             last_exception = e
 
-            if retry_count >= retry_config.max_retries:
+            if retry_count >= retry_policy.max_retries:
                 logger.error(
-                    f"Max retries ({retry_config.max_retries}) exceeded: {str(e)}"
+                    "Max retries (%s) exceeded: %s", retry_policy.max_retries, e
                 )
                 raise
 
             # Calculate next delay with exponential backoff
             if retry_count > 0:  # Don't increase delay on the first failure
-                delay = min(delay * retry_config.backoff_factor, retry_config.max_delay)
+                delay = min(delay * retry_policy.backoff_factor, retry_policy.max_delay)
 
             # Apply jitter if configured (±25% randomness)
-            if retry_config.jitter:
+            if retry_policy.jitter:
                 jitter_amount = delay * 0.25
                 delay = delay + random.uniform(-jitter_amount, jitter_amount)
                 # Ensure delay doesn't go negative due to jitter
                 delay = max(delay, 0.1)
 
             logger.warning(
-                f"Retry {retry_count+1}/{retry_config.max_retries} after error: {str(e)}. "
-                f"Retrying in {delay:.2f}s"
+                "Retry %s/%s after error: %s. Retrying in %.2fs",
+                retry_count + 1,
+                retry_policy.max_retries,
+                e,
+                delay,
             )
 
             # Call the optional retry callback if provided
@@ -113,7 +118,7 @@ async def retry_with_backoff(
 
 
 def with_retry(
-    retry_config: Optional[RetryConfig] = None,
+    retry_policy: RetryPolicy,
     retry_exceptions: tuple[type[Exception], ...] = (Exception,),
 ) -> Callable[[Callable[P, Awaitable[T]]], Callable[P, Awaitable[T]]]:
     """
@@ -132,7 +137,7 @@ def with_retry(
         async def wrapper(*args: P.args, **kwargs: P.kwargs) -> T:
             return await retry_with_backoff(
                 lambda: fn(*args, **kwargs),
-                retry_config=retry_config,
+                retry_policy=retry_policy,
                 retry_exceptions=retry_exceptions,
             )