boto3-assist 0.34.0__py3-none-any.whl → 0.36.0__py3-none-any.whl

boto3_assist/__init__.py

@@ -0,0 +1,10 @@
+"""
+Geek Cafe, LLC
+Maintainers: Eric Wilson
+MIT License. See Project Root for the license information.
+"""
+
+from .connection import Connection
+from .connection_pool import ConnectionPool
+
+__all__ = ["Connection", "ConnectionPool"]

boto3_assist/connection.py

@@ -5,6 +5,7 @@ MIT License.  See Project Root for the license information.
 """
 
 from typing import Optional, List
+import warnings
 
 from aws_lambda_powertools import Logger
 from botocore.config import Config
@@ -13,6 +14,7 @@ from boto3_assist.environment_services.environment_variables import (
     EnvironmentVariables,
 )
 from boto3_assist.connection_tracker import ConnectionTracker
+from boto3_assist.connection_pool import ConnectionPool
 
 
 logger = Logger()
@@ -35,6 +37,7 @@ class Connection:
         assume_role_chain: Optional[List[str]] = None,
         assume_role_duration_seconds: Optional[int] = 3600,
         config: Optional[Config] = None,
+        use_connection_pool: bool = False,
     ) -> None:
         self.__aws_profile = aws_profile
         self.__aws_region = aws_region
@@ -47,6 +50,8 @@ class Connection:
         self.__assume_role_chain = assume_role_chain
         self.__assume_role_duration_seconds = assume_role_duration_seconds
         self.__config = config
+        self.__use_connection_pool = use_connection_pool
+
         if self.__service_name is None:
             raise RuntimeError(
                 "Service Name is not available. The service name is required."
@@ -54,6 +59,18 @@ class Connection:
 
         self.raise_on_error: bool = True
 
+        # Issue deprecation warning if not using connection pool
+        if not use_connection_pool:
+            warnings.warn(
+                f"Creating {service_name} Connection without connection pooling. "
+                "This creates a new boto3 session on each instantiation, which can impact "
+                "Lambda performance. Consider using Connection.from_pool() or "
+                "use_connection_pool=True for better performance in Lambda functions. "
+                "The default will change to use_connection_pool=True in boto3-assist v2.0.0.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
     def setup(self, setup_source: Optional[str] = None) -> None:
         """
         Setup the environment.  Automatically called via init.
@@ -139,12 +156,74 @@ class Connection:
         logger.debug("Setting Service Name")
         self.__service_name = value
 
+    @classmethod
+    def from_pool(
+        cls,
+        service_name: str,
+        aws_profile: Optional[str] = None,
+        aws_region: Optional[str] = None,
+        aws_end_point_url: Optional[str] = None,
+        config: Optional[Config] = None,
+        **kwargs,
+    ) -> "Connection":
+        """
+        Create connection using connection pool (recommended for Lambda).
+
+        This is the recommended pattern for Lambda functions as it reuses
+        boto3 sessions across invocations in warm containers, reducing
+        connection overhead and improving performance.
+
+        Args:
+            service_name: AWS service name (e.g., 's3', 'dynamodb', 'sqs')
+            aws_profile: AWS profile name (optional)
+            aws_region: AWS region (optional)
+            aws_end_point_url: Custom endpoint URL (optional, for moto testing)
+            config: Botocore Config object (optional)
+            **kwargs: Additional Connection parameters
+
+        Returns:
+            Connection instance configured to use connection pool
+
+        Example:
+            >>> # Recommended pattern for Lambda
+            >>> conn = Connection.from_pool(service_name="dynamodb")
+            >>> client = conn.session.client
+            >>>
+            >>> # Subsequent calls reuse the same session
+            >>> conn2 = Connection.from_pool(service_name="dynamodb")
+            >>> assert conn.session is conn2.session
+        """
+        return cls(
+            service_name=service_name,
+            aws_profile=aws_profile,
+            aws_region=aws_region,
+            aws_end_point_url=aws_end_point_url,
+            config=config,
+            use_connection_pool=True,
+            **kwargs,
+        )
+
     @property
     def session(self) -> Boto3SessionManager:
         """Session"""
-        if self.__session is None:
-            self.setup(setup_source="session init")
-
-        if self.__session is None:
-            raise RuntimeError("Session is not available")
-        return self.__session
+        if self.__use_connection_pool:
+            # Use connection pool for session management
+            pool = ConnectionPool.get_instance()
+            return pool.get_session(
+                service_name=self.service_name,
+                aws_profile=self.aws_profile,
+                aws_region=self.aws_region,
+                aws_endpoint_url=self.end_point_url,
+                config=self.__config,
+                assume_role_arn=self.__assume_role_arn,
+                assume_role_chain=self.__assume_role_chain,
+                assume_role_duration_seconds=self.__assume_role_duration_seconds,
+            )
+        else:
+            # Legacy behavior: create session on demand
+            if self.__session is None:
+                self.setup(setup_source="session init")
+
+            if self.__session is None:
+                raise RuntimeError("Session is not available")
+            return self.__session

boto3_assist/connection_pool.py

@@ -0,0 +1,179 @@
+"""
+Geek Cafe, LLC
+Maintainers: Eric Wilson
+MIT License. See Project Root for the license information.
+
+Connection pooling for boto3 sessions to improve Lambda performance.
+"""
+
+from typing import Dict, Optional
+from aws_lambda_powertools import Logger
+from .boto3session import Boto3SessionManager
+
+logger = Logger()
+
+
+class ConnectionPool:
+    """
+    Singleton connection pool for reusing boto3 sessions.
+
+    Recommended for Lambda functions to minimize connection overhead and
+    improve performance in warm containers.
+
+    Example:
+        >>> pool = ConnectionPool.get_instance()
+        >>> session = pool.get_session(service_name="dynamodb")
+        >>> client = session.client
+
+        # Subsequent calls reuse the same session
+        >>> session2 = pool.get_session(service_name="dynamodb")
+        >>> assert session is session2  # Same instance
+    """
+
+    _instance: Optional["ConnectionPool"] = None
+
+    def __init__(self):
+        """Initialize connection pool. Use get_instance() instead."""
+        self._connections: Dict[str, Boto3SessionManager] = {}
+
+    @classmethod
+    def get_instance(cls) -> "ConnectionPool":
+        """
+        Get singleton instance of the connection pool.
+
+        Returns:
+            ConnectionPool: Singleton instance
+        """
+        if cls._instance is None:
+            logger.debug("Creating new ConnectionPool instance")
+            cls._instance = ConnectionPool()
+        return cls._instance
+
+    def get_session(
+        self,
+        service_name: str,
+        aws_profile: Optional[str] = None,
+        aws_region: Optional[str] = None,
+        aws_endpoint_url: Optional[str] = None,
+        **kwargs,
+    ) -> Boto3SessionManager:
+        """
+        Get or create cached session for service.
+
+        Sessions are cached based on service_name, profile, region, and endpoint.
+        Subsequent calls with the same parameters return the cached session.
+
+        Args:
+            service_name: AWS service name (e.g., 's3', 'dynamodb', 'sqs')
+            aws_profile: AWS profile name (optional)
+            aws_region: AWS region (optional, defaults to environment/config)
+            aws_endpoint_url: Custom endpoint URL (optional, useful for moto testing)
+            **kwargs: Additional Boto3SessionManager parameters
+
+        Returns:
+            Boto3SessionManager: Cached or newly created session manager
+
+        Example:
+            >>> pool = ConnectionPool.get_instance()
+            >>> # First call creates new session
+            >>> s3_session = pool.get_session(service_name="s3")
+            >>> # Second call returns cached session
+            >>> s3_session2 = pool.get_session(service_name="s3")
+            >>> assert s3_session is s3_session2
+        """
+        key = self._make_key(service_name, aws_profile, aws_region, aws_endpoint_url)
+
+        if key not in self._connections:
+            logger.debug(
+                f"Creating new session for {service_name}",
+                extra={
+                    "service_name": service_name,
+                    "aws_profile": aws_profile,
+                    "aws_region": aws_region,
+                    "cache_key": key,
+                },
+            )
+            self._connections[key] = Boto3SessionManager(
+                service_name=service_name,
+                aws_profile=aws_profile,
+                aws_region=aws_region,
+                aws_endpoint_url=aws_endpoint_url,
+                **kwargs,
+            )
+        else:
+            logger.debug(
+                f"Reusing cached session for {service_name}",
+                extra={
+                    "service_name": service_name,
+                    "cache_key": key,
+                    "total_cached_sessions": len(self._connections),
+                },
+            )
+
+        return self._connections[key]
+
+    def reset(self):
+        """
+        Reset all connections in the pool.
+
+        This clears all cached sessions. Useful for testing or when you need
+        to force recreation of all connections.
+
+        Warning:
+            This should only be used in testing scenarios. In production Lambda
+            functions, connections should persist across invocations.
+
+        Example:
+            >>> pool = ConnectionPool.get_instance()
+            >>> pool.get_session(service_name="s3")
+            >>> pool.reset()  # Clear all cached sessions
+            >>> # Next call will create new session
+            >>> pool.get_session(service_name="s3")
+        """
+        logger.debug(f"Resetting connection pool ({len(self._connections)} sessions)")
+        self._connections.clear()
+
+    def get_stats(self) -> Dict[str, int]:
+        """
+        Get statistics about the connection pool.
+
+        Returns:
+            Dict with pool statistics:
+                - total_connections: Number of cached sessions
+                - services: Number of unique services
+
+        Example:
+            >>> pool = ConnectionPool.get_instance()
+            >>> pool.get_session(service_name="s3")
+            >>> pool.get_session(service_name="dynamodb")
+            >>> stats = pool.get_stats()
+            >>> print(stats)
+            {'total_connections': 2, 'services': 2}
+        """
+        services = set()
+        for key in self._connections.keys():
+            service_name = key.split(":")[0]
+            services.add(service_name)
+
+        return {"total_connections": len(self._connections), "services": len(services)}
+
+    @staticmethod
+    def _make_key(
+        service_name: str,
+        profile: Optional[str],
+        region: Optional[str],
+        endpoint: Optional[str],
+    ) -> str:
+        """
+        Create cache key from connection parameters.
+
+        Args:
+            service_name: AWS service name
+            profile: AWS profile name (or None)
+            region: AWS region (or None)
+            endpoint: Custom endpoint URL (or None)
+
+        Returns:
+            str: Cache key for this combination of parameters
+        """
+        return f"{service_name}:{profile}:{region}:{endpoint}"

boto3_assist/dynamodb/__init__.py

@@ -0,0 +1,9 @@
+"""
+Geek Cafe, LLC
+Maintainers: Eric Wilson
+MIT License. See Project Root for the license information.
+"""
+
+from .dynamodb import DynamoDB
+
+__all__ = ["DynamoDB"]