sendgrid-async 2.2.0__tar.gz → 2.3.0__tar.gz

{sendgrid_async-2.2.0 → sendgrid_async-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: sendgrid-async
-Version: 2.2.0
+Version: 2.3.0
 Summary: SendGrid using an httpx client
 Home-page: https://github.com/EM51641/async-sendgrid-
 License: MIT
@@ -131,17 +131,22 @@ To disable retries entirely, set `retry_attempts=0`:
 pool = ConnectionPool(retry_attempts=0)
 ```
 
-You can also override the retry strategy per call:
+### Shutdown
+
+When your application is shutting down, call `shutdown()` on the pool to close all connections and release resources:
 
 ```python
-# Override both retry attempts and backoff for this call
-response = await sendgrid.send(email, retry=10, backoff=1.0)
+pool = ConnectionPool()
+sendgrid = SendgridAPI(api_key="YOUR_API_KEY", pool=pool)
+
+# ... send emails ...
 
-# Override just one (the other keeps the pool default)
-response = await sendgrid.send(email, retry=3)
-response = await sendgrid.send(email, backoff=0.1)
+# On application shutdown
+await pool.shutdown()
 ```
 
+> **Note:** Per-call `retry` or `backoff` overrides on `send()` create and tear down an ephemeral connection (TCP + TLS handshake) for every request. Because an email send is a lightweight operation — a small JSON payload answered with a `202` — the connection overhead can easily exceed the request itself. Configure retry and backoff on the `ConnectionPool` at initialization instead.
+
 ### Send emails on behalf of another user
 
 Send emails on behalf of subusers:

{sendgrid_async-2.2.0 → sendgrid_async-2.3.0}/README.md

@@ -102,17 +102,22 @@ To disable retries entirely, set `retry_attempts=0`:
 pool = ConnectionPool(retry_attempts=0)
 ```
 
-You can also override the retry strategy per call:
+### Shutdown
+
+When your application is shutting down, call `shutdown()` on the pool to close all connections and release resources:
 
 ```python
-# Override both retry attempts and backoff for this call
-response = await sendgrid.send(email, retry=10, backoff=1.0)
+pool = ConnectionPool()
+sendgrid = SendgridAPI(api_key="YOUR_API_KEY", pool=pool)
+
+# ... send emails ...
 
-# Override just one (the other keeps the pool default)
-response = await sendgrid.send(email, retry=3)
-response = await sendgrid.send(email, backoff=0.1)
+# On application shutdown
+await pool.shutdown()
 ```
 
+> **Note:** Per-call `retry` or `backoff` overrides on `send()` create and tear down an ephemeral connection (TCP + TLS handshake) for every request. Because an email send is a lightweight operation — a small JSON payload answered with a `202` — the connection overhead can easily exceed the request itself. Configure retry and backoff on the `ConnectionPool` at initialization instead.
+
 ### Send emails on behalf of another user
 
 Send emails on behalf of subusers:

sendgrid_async-2.3.0/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.0 → sendgrid_async-2.3.0}/async_sendgrid/pool.py

@@ -6,7 +6,7 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
-from httpx import AsyncClient, Limits  # type: ignore
+from httpx import AsyncClient, AsyncHTTPTransport, Limits  # type: ignore
 from httpx_retries import Retry, RetryTransport  # type: ignore
 
 if TYPE_CHECKING:
@@ -27,6 +27,7 @@ class ConnectionPool:
         retry_attempts: int = 5,
         backoff_factor: float = 0.5,
         backoff_jitter: float = 1.0,
+        timeout: float = 5.0,
     ) -> None:
         """
         Initialize the connection pool.
@@ -51,10 +52,13 @@ class ConnectionPool:
             backoff_jitter (float, optional):
                 Jitter multiplier applied to the backoff time,
                 between 0 and 1. Defaults to 1.0.
+            timeout (float, optional):
+                Request timeout in seconds. Defaults to 5.0.
         """
         self._validate_retry_attempts(retry_attempts)
         self._validate_backoff_factor(backoff_factor)
         self._validate_backoff_jitter(backoff_jitter)
+        self._validate_timeout(timeout)
 
         self._limits = Limits(
             max_connections=max_connections,
@@ -67,16 +71,44 @@ class ConnectionPool:
             backoff_jitter=backoff_jitter,
             allowed_methods=["POST"],
         )
+        self._timeout = timeout
         self._client: AsyncClient | None = None
+        self._shutdown = False
 
-    def _create_client(
+    def _create_client(self, headers: dict[str, Any]) -> AsyncClient:
+        """
+        Get or create the long-lived HTTP client backed by the pool.
+
+        Args:
+            headers (dict[str, Any]): The headers to use for the client.
+
+        Returns:
+            AsyncClient: The configured HTTP client.
+        """
+        if self._client is not None and not self._client.is_closed:
+            return self._client
+
+        transport = RetryTransport(
+            transport=AsyncHTTPTransport(limits=self._limits),
+            retry=self._retry,
+        )
+        self._client = AsyncClient(
+            headers=headers,
+            timeout=self._timeout,
+            transport=transport,
+        )
+        return self._client
+
+    def _create_ephemeral_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.
+        Create a single-use HTTP client with custom retry/backoff settings.
+
+        The caller is responsible for closing the returned client.
 
         Args:
             headers (dict[str, Any]): The headers to use for the client.
@@ -86,28 +118,43 @@ class ConnectionPool:
                 Uses the pool default when not set.
 
         Returns:
-            AsyncClient: The configured HTTP client.
+            AsyncClient: An ephemeral HTTP client.
         """
-        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(retry=retry_strategy)
+        if retry is not None:
+            self._validate_retry_attempts(retry)
+        if backoff is not None:
+            self._validate_backoff_factor(backoff)
+
+        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(),
+            retry=retry_strategy,
+        )
         return AsyncClient(
             headers=headers,
-            limits=self._limits,
-            timeout=5.0,
+            timeout=self._timeout,
             transport=transport,
         )
 
+    @property
+    def is_shutdown(self) -> bool:
+        """Whether the pool has been explicitly shut down."""
+        return self._shutdown
+
+    async def shutdown(self) -> None:
+        """Close all clients and release their connections."""
+        self._shutdown = True
+        if self._client is not None and not self._client.is_closed:
+            await self._client.aclose()
+            self._client = None
+
     @staticmethod
     def _validate_retry_attempts(retry_attempts: int) -> None:
         if not isinstance(retry_attempts, int) or retry_attempts < 0:
@@ -123,6 +170,11 @@ class ConnectionPool:
         if not isinstance(backoff_jitter, (int, float)) or backoff_jitter < 0:
             raise ValueError("backoff_jitter must be a positive number")
 
+    @staticmethod
+    def _validate_timeout(timeout: float) -> None:
+        if not isinstance(timeout, (int, float)) or timeout <= 0:
+            raise ValueError("timeout must be a positive number")
+
     @property
     def limits(self) -> Limits:
         """
@@ -141,7 +193,8 @@ class ConnectionPool:
             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})"
+            f"backoff_jitter={self._retry.backoff_jitter}, "
+            f"timeout={self._timeout})"
         )
 
     def __str__(self) -> str:

{sendgrid_async-2.2.0 → sendgrid_async-2.3.0}/async_sendgrid/sendgrid.py

@@ -129,25 +129,37 @@ class SendgridAPI(BaseSendgridAPI):
     ) -> Response:
         """
         Make a Twilio SendGrid v3 API request with the request body generated
-        by the Mail object
+        by the Mail object.
+
+        .. warning::
+            Calling this method repeatedly with per-call ``retry`` or
+            ``backoff`` overrides will open and close a new connection
+            each time, which can degrade throughput significantly.
+            For regular sends, configure the desired retry and backoff
+            on the ``ConnectionPool`` once at initialization.
 
         Args:
             email: The Twilio SendGrid v3 API request body generated
-                by the Mail object or dict
+                by the Mail object or dict.
             retry: Override the number of retry attempts for this
-                request. Uses the client default when not set.
+                request.  Creates an ephemeral client.
+                Uses the pool default when not set.
             backoff: Override the backoff factor for this request.
-                Uses the client default when not set.
+                Creates an ephemeral client.
+                Uses the pool default when not set.
 
         Returns:
-            The Twilio SendGrid v3 API response
+            The Twilio SendGrid v3 API response.
         """
         self._check_session_closed()
         json_message = email.get()
 
         if retry is not None or backoff is not None:
-            async with self._build_client(retry, backoff) as session:
+            session = self._build_client(retry, backoff)
+            try:
                 return await self._send(session, json_message)
+            finally:
+                await session.aclose()
 
         return await self._send(self._session, json_message)
 
@@ -161,7 +173,7 @@ class SendgridAPI(BaseSendgridAPI):
         retry: Optional[int] = None,
         backoff: Optional[float] = None,
     ) -> AsyncClient:
-        return self._pool._create_client(
+        return self._pool._create_ephemeral_client(
             self._headers, retry=retry, backoff=backoff
         )
 
@@ -169,13 +181,23 @@ class SendgridAPI(BaseSendgridAPI):
         """
         Check if the session is closed.
 
+        If the pool was explicitly shut down, raises
+        ``SessionClosedException``.  Otherwise, transparently
+        rebuilds the underlying client.
+
         Raises:
-            SessionClosedException: If the session is closed.
+            SessionClosedException: If the pool has been shut down.
         """
-        if self._session.is_closed:
+        if not self._session.is_closed:
+            return
+
+        if self._pool.is_shutdown:
             logger.error("Session not initialized")
             raise SessionClosedException("Session not initialized")
 
+        logger.debug("Session closed unexpectedly, rebuilding client")
+        self._session = self._pool._create_client(self._headers)
+
     def __repr__(self) -> str:
         return (
             f"SendgridAPI("

{sendgrid_async-2.2.0 → sendgrid_async-2.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "sendgrid-async"
-version = "2.2.0"
+version = "2.3.0"
 description = "SendGrid using an httpx client"
 license = "MIT"
 authors = ["Elyes Mahjoubi <elyesmahjoubi@gmail.com>"]

sendgrid_async-2.2.0/async_sendgrid/__init__.py

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