boto3-assist 0.35.0__tar.gz → 0.36.0__tar.gz

boto3_assist-0.36.0/CHANGELOG.md

@@ -0,0 +1,101 @@
+# Changelog
+
+All notable changes to boto3-assist will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.36.0] - 2026-01-25
+
+### Added
+- **Connection Pooling** - New `ConnectionPool` class for reusing boto3 sessions across Lambda invocations
+  - Singleton pattern caches sessions by service, profile, region, and endpoint
+  - Significantly improves Lambda performance by reducing connection overhead
+  - `ConnectionPool.get_instance()` - Get singleton pool instance
+  - `ConnectionPool.get_session()` - Get or create cached session
+  - `ConnectionPool.reset()` - Clear cache (for testing)
+  - `ConnectionPool.get_stats()` - Pool statistics
+
+- **Factory Methods** - New recommended pattern for creating connections
+  - `Connection.from_pool()` - Create connection using pool (recommended for Lambda)
+  - `DynamoDB.from_pool()` - Create DynamoDB connection using pool
+  - `S3.from_pool()` - Create S3 connection using pool
+  - `SQSConnection.from_pool()` - Create SQS connection using pool
+  - All service classes support `use_connection_pool` parameter
+
+- **Package Exports** - Added `__init__.py` files for cleaner imports
+  - `from boto3_assist import Connection, ConnectionPool`
+  - `from boto3_assist.dynamodb import DynamoDB`
+  - `from boto3_assist.s3 import S3`
+  - `from boto3_assist.sqs import SQSConnection`
+
+### Changed
+- **Deprecation Warning** - Connections created without pooling now show deprecation warning
+  - Warning guides users to new `.from_pool()` pattern
+  - Default will change to `use_connection_pool=True` in v2.0.0
+  - Existing code continues to work unchanged
+
+### Backward Compatibility
+- ✅ All existing code works without modification
+- ✅ Deprecation warnings are informational only
+- ✅ No breaking changes in this release
+
+### Migration Guide
+```python
+# DynamoDB
+# Old pattern (still works, shows deprecation warning)
+db = DynamoDB()
+# New pattern (recommended for Lambda)
+db = DynamoDB.from_pool()
+
+# S3
+# Old pattern (still works, shows deprecation warning)
+s3 = S3()
+# New pattern (recommended for Lambda)
+s3 = S3.from_pool()
+
+# SQS
+# Old pattern (still works, shows deprecation warning)
+sqs = SQSConnection()
+# New pattern (recommended for Lambda)
+sqs = SQSConnection.from_pool()
+
+# Explicit opt-in (any service)
+db = DynamoDB(use_connection_pool=True)
+s3 = S3(use_connection_pool=True)
+sqs = SQSConnection(use_connection_pool=True)
+```
+
+### Testing
+- Added 16 new tests for connection pooling
+- All 107 tests passing (91 DynamoDB + 16 connection pool)
+- Comprehensive backward compatibility testing
+
+## [0.35.0] - Previous Release
+
+### Features
+- DynamoDB operations (save, query, update, batch, transactions)
+- Session management with role assumption
+- Decimal conversion for DynamoDB
+- Conditional expressions
+- Update expressions (SET, ADD, REMOVE)
+- Transaction support
+- Batch operations
+- Connection tracking and monitoring
+
+---
+
+## Upgrade Notes
+
+### From 0.35.0 to 0.36.0
+No breaking changes. Optionally migrate to `.from_pool()` pattern for better Lambda performance.
+
+### Future Breaking Changes
+- **v2.0.0** (planned): `use_connection_pool=True` will become the default
+  - To preserve old behavior in v2.0.0: `Connection(service_name="...", use_connection_pool=False)`
+  - Timeline: 6+ months from v0.36.0 release
+
+---
+
+[0.36.0]: https://github.com/geekcafe/boto3-assist/compare/v0.35.0...v0.36.0
+[0.35.0]: https://github.com/geekcafe/boto3-assist/releases/tag/v0.35.0

{boto3_assist-0.35.0 → boto3_assist-0.36.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: boto3_assist
-Version: 0.35.0
+Version: 0.36.0
 Summary: Additional boto3 wrappers to make your life a little easier
 Author-email: Eric Wilson <boto3-assist@geekcafe.com>
 License-File: LICENSE-EXPLAINED.txt

{boto3_assist-0.35.0 → boto3_assist-0.36.0}/pyproject.toml

@@ -15,7 +15,7 @@ addopts = "-m 'not integration'"
 
 [project]
 name = "boto3_assist"
-version = "0.35.0"
+version = "0.36.0"
 
 authors = [
   { name="Eric Wilson", email="boto3-assist@geekcafe.com" }

boto3_assist-0.36.0/src/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-0.35.0 → boto3_assist-0.36.0}/src/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-0.36.0/src/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-0.36.0/src/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"]