sendgrid-async 2.1.2__tar.gz → 2.2.1__tar.gz

{sendgrid_async-2.1.2 → sendgrid_async-2.2.1}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.1
 Name: sendgrid-async
-Version: 2.1.2
+Version: 2.2.1
 Summary: SendGrid using an httpx client
 Home-page: https://github.com/EM51641/async-sendgrid-
 License: MIT
 Keywords: sendgrid,client,async
 Author: Elyes Mahjoubi
 Author-email: elyesmahjoubi@gmail.com
-Requires-Python: >=3.10,<4.0
+Requires-Python: >=3.10
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
@@ -17,7 +17,9 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: httpx (>=0.24.1,<0.29.0)
+Requires-Dist: httpx-retries (>=0.4.0)
 Requires-Dist: opentelemetry-api (>=1.34.0,<2.0.0)
 Requires-Dist: opentelemetry-exporter-otlp-proto-grpc (>=1.34.0,<2.0.0)
 Requires-Dist: opentelemetry-sdk (>=1.34.0,<2.0.0)
@@ -93,6 +95,53 @@ sendgrid = SendgridAPI(
 )
 ```
 
+### Retry Configuration
+
+By default, requests are automatically retried up to 5 times with exponential backoff on transient failures (429 Too Many Requests, 502, 503, 504, and timeouts).
+
+The delay between retries is calculated as:
+
+```
+delay = backoff_factor * (2 ** attempt) * random(1 - backoff_jitter, 1)
+```
+
+With the defaults (`backoff_factor=0.5`, `backoff_jitter=1.0`), delays range from 0 to 1s, 0 to 2s, 0 to 4s, etc. Jitter prevents thundering herd problems when multiple clients retry simultaneously.
+
+Customize the retry behavior through the connection pool:
+
+```python
+from async_sendgrid import SendgridAPI
+from async_sendgrid.pool import ConnectionPool
+
+pool = ConnectionPool(
+    retry_attempts=3,    # Maximum retry attempts (default: 5)
+    backoff_factor=1.0,  # Backoff multiplier in seconds (default: 0.5)
+    backoff_jitter=0.0,  # Jitter multiplier, 0 to 1 (default: 1.0)
+)
+
+sendgrid = SendgridAPI(
+    api_key="YOUR_API_KEY",
+    pool=pool,
+)
+```
+
+To disable retries entirely, set `retry_attempts=0`:
+
+```python
+pool = ConnectionPool(retry_attempts=0)
+```
+
+You can also override the retry strategy per call:
+
+```python
+# Override both retry attempts and backoff for this call
+response = await sendgrid.send(email, retry=10, backoff=1.0)
+
+# Override just one (the other keeps the pool default)
+response = await sendgrid.send(email, retry=3)
+response = await sendgrid.send(email, backoff=0.1)
+```
+
 ### Send emails on behalf of another user
 
 Send emails on behalf of subusers:

{sendgrid_async-2.1.2 → sendgrid_async-2.2.1}/README.md

@@ -66,6 +66,53 @@ sendgrid = SendgridAPI(
 )
 ```
 
+### Retry Configuration
+
+By default, requests are automatically retried up to 5 times with exponential backoff on transient failures (429 Too Many Requests, 502, 503, 504, and timeouts).
+
+The delay between retries is calculated as:
+
+```
+delay = backoff_factor * (2 ** attempt) * random(1 - backoff_jitter, 1)
+```
+
+With the defaults (`backoff_factor=0.5`, `backoff_jitter=1.0`), delays range from 0 to 1s, 0 to 2s, 0 to 4s, etc. Jitter prevents thundering herd problems when multiple clients retry simultaneously.
+
+Customize the retry behavior through the connection pool:
+
+```python
+from async_sendgrid import SendgridAPI
+from async_sendgrid.pool import ConnectionPool
+
+pool = ConnectionPool(
+    retry_attempts=3,    # Maximum retry attempts (default: 5)
+    backoff_factor=1.0,  # Backoff multiplier in seconds (default: 0.5)
+    backoff_jitter=0.0,  # Jitter multiplier, 0 to 1 (default: 1.0)
+)
+
+sendgrid = SendgridAPI(
+    api_key="YOUR_API_KEY",
+    pool=pool,
+)
+```
+
+To disable retries entirely, set `retry_attempts=0`:
+
+```python
+pool = ConnectionPool(retry_attempts=0)
+```
+
+You can also override the retry strategy per call:
+
+```python
+# Override both retry attempts and backoff for this call
+response = await sendgrid.send(email, retry=10, backoff=1.0)
+
+# Override just one (the other keeps the pool default)
+response = await sendgrid.send(email, retry=3)
+response = await sendgrid.send(email, backoff=0.1)
+```
+
 ### Send emails on behalf of another user
 
 Send emails on behalf of subusers:

sendgrid_async-2.2.1/async_sendgrid/__init__.py

@@ -0,0 +1,13 @@
+from importlib.metadata import PackageNotFoundError, version
+
+from .sendgrid import SendgridAPI  # noqa
+from .pool import ConnectionPool  # noqa
+
+__version__ = "0.0.0-dev"
+
+try:
+    __version__ = version("sendgrid-async")
+except PackageNotFoundError:
+    pass
+
+__all__ = ["SendgridAPI", "ConnectionPool"]

sendgrid_async-2.2.1/async_sendgrid/pool.py

@@ -0,0 +1,155 @@
+"""
+Connection pool manager for SendGrid API requests.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from httpx import AsyncClient, AsyncHTTPTransport, Limits  # type: ignore
+from httpx_retries import Retry, RetryTransport  # type: ignore
+
+if TYPE_CHECKING:
+    from typing import Any
+
+
+class ConnectionPool:
+    """
+    A connection pool manager for SendGrid API requests.
+    This is a private class and is not meant to be used directly.
+    """
+
+    def __init__(
+        self,
+        max_connections: int = 10,
+        max_keepalive_connections: int = 5,
+        keepalive_expiry: float = 5.0,
+        retry_attempts: int = 5,
+        backoff_factor: float = 0.5,
+        backoff_jitter: float = 1.0,
+    ) -> None:
+        """
+        Initialize the connection pool.
+
+        Args:
+            max_connections (int, optional):
+                Maximum number of concurrent connections.
+                Defaults to 10.
+            max_keepalive_connections (int, optional):
+                Maximum number of keep-alive connections.
+                Defaults to 5.
+            keepalive_expiry (float, optional):
+                Keep-alive connection expiry time in
+                seconds. Defaults to 5.0.
+            retry_attempts (int, optional):
+                Maximum number of retry attempts for
+                transient failures (429, 5xx, timeouts).
+                Defaults to 5.
+            backoff_factor (float, optional):
+                Multiplier for exponential backoff between
+                retries. Defaults to 0.5.
+            backoff_jitter (float, optional):
+                Jitter multiplier applied to the backoff time,
+                between 0 and 1. Defaults to 1.0.
+        """
+        self._validate_retry_attempts(retry_attempts)
+        self._validate_backoff_factor(backoff_factor)
+        self._validate_backoff_jitter(backoff_jitter)
+
+        self._limits = Limits(
+            max_connections=max_connections,
+            max_keepalive_connections=max_keepalive_connections,
+            keepalive_expiry=keepalive_expiry,
+        )
+        self._retry = Retry(
+            total=retry_attempts,
+            backoff_factor=backoff_factor,
+            backoff_jitter=backoff_jitter,
+            allowed_methods=["POST"],
+        )
+        self._client: AsyncClient | None = None
+
+    def _create_client(
+        self,
+        headers: dict[str, Any],
+        retry: int | None = None,
+        backoff: float | None = None,
+    ) -> AsyncClient:
+        """
+        Get or create an HTTP client with the configured connection limits.
+
+        Args:
+            headers (dict[str, Any]): The headers to use for the client.
+            retry (int, optional): Override the number of retry attempts.
+                Uses the pool default when not set.
+            backoff (float, optional): Override the backoff factor.
+                Uses the pool default when not set.
+
+        Returns:
+            AsyncClient: The configured HTTP client.
+        """
+        if retry is not None:
+            self._validate_retry_attempts(retry)
+        if backoff is not None:
+            self._validate_backoff_factor(backoff)
+
+        retry_strategy = self._retry
+        if retry is not None or backoff is not None:
+            retry_strategy = Retry(
+                total=retry if retry is not None else self._retry.total,
+                backoff_factor=(
+                    backoff
+                    if backoff is not None
+                    else self._retry.backoff_factor
+                ),
+                backoff_jitter=self._retry.backoff_jitter,
+                allowed_methods=["POST"],
+            )
+        transport = RetryTransport(
+            transport=AsyncHTTPTransport(limits=self._limits),
+            retry=retry_strategy,
+        )
+        return AsyncClient(
+            headers=headers,
+            timeout=5.0,
+            transport=transport,
+        )
+
+    @staticmethod
+    def _validate_retry_attempts(retry_attempts: int) -> None:
+        if not isinstance(retry_attempts, int) or retry_attempts < 0:
+            raise ValueError("retry_attempts must be a positive integer")
+
+    @staticmethod
+    def _validate_backoff_factor(backoff_factor: float) -> None:
+        if not isinstance(backoff_factor, (int, float)) or backoff_factor < 0:
+            raise ValueError("backoff_factor must be a positive number")
+
+    @staticmethod
+    def _validate_backoff_jitter(backoff_jitter: float) -> None:
+        if not isinstance(backoff_jitter, (int, float)) or backoff_jitter < 0:
+            raise ValueError("backoff_jitter must be a positive number")
+
+    @property
+    def limits(self) -> Limits:
+        """
+        Get the current connection limits.
+
+        Returns:
+            Limits: The current connection limits configuration.
+        """
+        return self._limits
+
+    def __repr__(self) -> str:
+        return (
+            f"ConnectionPool("
+            f"max_connections={self._limits.max_connections}, "
+            f"max_keepalive_connections={self._limits.max_keepalive_connections}, "  # noqa: E501
+            f"keepalive_expiry={self._limits.keepalive_expiry}, "
+            f"retry_attempts={self._retry.total}, "
+            f"backoff_factor={self._retry.backoff_factor}, "
+            f"backoff_jitter={self._retry.backoff_jitter})"
+        )
+
+    def __str__(self) -> str:
+        return repr(self)

{sendgrid_async-2.1.2 → sendgrid_async-2.2.1}/async_sendgrid/sendgrid.py

@@ -50,7 +50,12 @@ class BaseSendgridAPI(ABC):
         """Not implemented"""
 
     @abstractmethod
-    async def send(self, message: Mail) -> Response:
+    async def send(
+        self,
+        message: Mail,
+        retry: Optional[int] = None,
+        backoff: Optional[float] = None,
+    ) -> Response:
         """Not implemented"""
 
 
@@ -116,7 +121,12 @@ class SendgridAPI(BaseSendgridAPI):
         return self._session
 
     @trace_client()
-    async def send(self, email: Mail) -> Response:
+    async def send(
+        self,
+        email: Mail,
+        retry: Optional[int] = None,
+        backoff: Optional[float] = None,
+    ) -> Response:
         """
         Make a Twilio SendGrid v3 API request with the request body generated
         by the Mail object
@@ -124,16 +134,36 @@ class SendgridAPI(BaseSendgridAPI):
         Args:
             email: The Twilio SendGrid v3 API request body generated
                 by the Mail object or dict
+            retry: Override the number of retry attempts for this
+                request. Uses the client default when not set.
+            backoff: Override the backoff factor for this request.
+                Uses the client default when not set.
 
         Returns:
             The Twilio SendGrid v3 API response
         """
         self._check_session_closed()
         json_message = email.get()
-        response = await self._session.post(
-            url=self._endpoint, json=json_message
+
+        if retry is not None or backoff is not None:
+            async with self._build_client(retry, backoff) as session:
+                return await self._send(session, json_message)
+
+        return await self._send(self._session, json_message)
+
+    async def _send(
+        self, client: AsyncClient, json_message: dict[str, Any]
+    ) -> Response:
+        return await client.post(url=self._endpoint, json=json_message)
+
+    def _build_client(
+        self,
+        retry: Optional[int] = None,
+        backoff: Optional[float] = None,
+    ) -> AsyncClient:
+        return self._pool._create_client(
+            self._headers, retry=retry, backoff=backoff
         )
-        return response
 
     def _check_session_closed(self):
         """
@@ -146,8 +176,12 @@ class SendgridAPI(BaseSendgridAPI):
             logger.error("Session not initialized")
             raise SessionClosedException("Session not initialized")
 
-    def __str__(self) -> str:
-        return f"SendGrid API Client\n  • Endpoint: {self._endpoint}\n"
-
     def __repr__(self) -> str:
-        return f"SendgridAPI(endpoint={self._endpoint})"
+        return (
+            f"SendgridAPI("
+            f"endpoint={self._endpoint!r}, "
+            f"pool={self._pool!r})"
+        )
+
+    def __str__(self) -> str:
+        return repr(self)

{sendgrid_async-2.1.2 → sendgrid_async-2.2.1}/async_sendgrid/telemetry.py

@@ -75,11 +75,13 @@ def trace_client():
             return func
 
         @wraps(func)
-        async def wrapper(self: SendgridAPI, email: Mail) -> Response:
+        async def wrapper(
+            self: SendgridAPI, email: Mail, **kwargs: Any
+        ) -> Response:
             span = create_span(_SPAN_NAME)
             try:
                 set_sendgrid_metrics(span, email)
-                response: Response = await func(self, email)
+                response: Response = await func(self, email, **kwargs)
                 set_http_metrics(span, response)
                 return response
             except Exception as exc:

{sendgrid_async-2.1.2 → sendgrid_async-2.2.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "sendgrid-async"
-version = "2.1.2"
+version = "2.2.1"
 description = "SendGrid using an httpx client"
 license = "MIT"
 authors = ["Elyes Mahjoubi <elyesmahjoubi@gmail.com>"]
@@ -14,6 +14,7 @@ classifiers = [
     "Programming Language :: Python :: 3.11",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
 ]
 
 packages = [
@@ -26,9 +27,10 @@ include = [
 ]
 
 [tool.poetry.dependencies]
-python = "^3.10"
+python = ">=3.10"
 sendgrid = "^6.7.0"
 httpx = ">=0.24.1,<0.29.0"
+httpx-retries = ">=0.4.0"
 opentelemetry-api = "^1.34.0"
 opentelemetry-sdk = "^1.34.0"
 opentelemetry-exporter-otlp-proto-grpc = "^1.34.0"
@@ -37,6 +39,7 @@ opentelemetry-exporter-otlp-proto-grpc = "^1.34.0"
 pytest = "^8.4.0"
 pytest-asyncio = "^1.0.0"
 pytest-cov = "^6.1.1"
+pytest-httpserver = "^1.1.0"
 mypy = "^1.0.0"
 flake8 = "^7.2.0"
 black = "^25.1.0"

sendgrid_async-2.1.2/async_sendgrid/__init__.py

@@ -1,4 +0,0 @@
-from .sendgrid import SendgridAPI  # noqa
-
-__version__ = "2.0.2"
-__all__ = ["SendgridAPI"]

sendgrid_async-2.1.2/async_sendgrid/pool.py

@@ -1,72 +0,0 @@
-"""
-Connection pool manager for SendGrid API requests.
-"""
-
-from __future__ import annotations
-
-from typing import TYPE_CHECKING
-
-from httpx import AsyncClient, Limits  # type: ignore
-
-if TYPE_CHECKING:
-    from typing import Any
-
-
-class ConnectionPool:
-    """
-    A connection pool manager for SendGrid API requests.
-    This is a private class and is not meant to be used directly.
-    """
-
-    def __init__(
-        self,
-        max_connections: int = 10,
-        max_keepalive_connections: int = 5,
-        keepalive_expiry: float = 5.0,
-    ) -> None:
-        """
-        Initialize the connection pool.
-
-        Args:
-            max_connections (int, optional):
-                Maximum number of concurrent connections. Defaults to 10.
-            max_keepalive_connections (int, optional):
-                Maximum number of keep-alive connections. Defaults to 5.
-            keepalive_expiry (float, optional):
-                Keep-alive connection expiry time in seconds. Defaults to 5.0.
-        """
-        self._limits = Limits(
-            max_connections=max_connections,
-            max_keepalive_connections=max_keepalive_connections,
-            keepalive_expiry=keepalive_expiry,
-        )
-        self._client: AsyncClient | None = None
-
-    def _create_client(self, headers: dict[str, Any]) -> AsyncClient:
-        """
-        Get or create an HTTP client with the configured connection limits.
-
-        Args:
-            headers (dict[str, Any]): The headers to use for the client.
-
-        Returns:
-            AsyncClient: The configured HTTP client.
-        """
-        return AsyncClient(headers=headers, limits=self._limits, timeout=5.0)
-
-    @property
-    def limits(self) -> Limits:
-        """
-        Get the current connection limits.
-
-        Returns:
-            Limits: The current connection limits configuration.
-        """
-        return self._limits
-
-    def __str__(self) -> str:
-        return (
-            f"ConnectionPool(max_connections={self._limits.max_connections}, "
-            f"max_keepalive={self._limits.max_keepalive_connections}, "
-            f"keepalive_expiry={self._limits.keepalive_expiry})"
-        )