Usage

Basic Usage

Here’s a basic example of how to use botowrap:

import logging
import boto3
from botowrap.core import ExtensionManager
from botowrap.extensions.dynamodb import DynamoDBExtension, DynamoDBConfig

# Set up logging to see the enhancements in action
logging.basicConfig(level=logging.INFO)

# 1) Create an extension manager (uses the default boto3 session)
mgr = ExtensionManager()

# 2) Configure and register the DynamoDB extension
ddb_config = DynamoDBConfig(
    max_retries=5,
    log_consumed=True,
    add_pagination=True,
    add_timestamps=True
)
mgr.register(DynamoDBExtension(ddb_config))

# 3) Bootstrap the extensions (this enhances boto3 clients)
mgr.bootstrap()

# Now any DynamoDB client you create will have all the enhancements
ddb = boto3.client('dynamodb')

# Use native Python types - automatic serialization
ddb.put_item(
    TableName='Users',
    Item={
        'UserId': 'alice',
        'Age': 30,
        'Active': True,
        'Metadata': {'LastLogin': '2023-01-01'}
    }
)

# Get item returns deserialized Python types
user = ddb.get_item(
    TableName='Users',
    Key={'UserId': 'alice'}
)
print(user['Item'])  # Python dict with native types

# Use pagination helpers
all_users = ddb.scan_all(TableName='Users')
print(all_users['Items'])  # All items in one response

Extension Configuration

Each extension in botowrap can be configured to suit your specific needs. For example, the DynamoDB extension can be configured with these options:

ddb_config = DynamoDBConfig(
    # Number of retries for throttling exceptions
    max_retries=5,

    # Whether to log DynamoDB consumed capacity
    log_consumed=True,

    # Add pagination helpers (scan_all, query_all)
    add_pagination=True,

    # Add automatic CreatedAt/UpdatedAt timestamps
    add_timestamps=True
)

Advanced Usage

Using Multiple Extensions

You can register multiple extensions with the same manager:

from botowrap.core import ExtensionManager
from botowrap.extensions.dynamodb import DynamoDBExtension, DynamoDBConfig

# Create manager
mgr = ExtensionManager()

# Register DynamoDB extension
mgr.register(DynamoDBExtension(DynamoDBConfig()))

# Register other extensions as they become available
# mgr.register(OtherExtension(OtherConfig()))

# Bootstrap all extensions
mgr.bootstrap()

Using a Custom Session

If you need to use a specific boto3 session:

import boto3
from botowrap.core import ExtensionManager

# Create a custom session
session = boto3.Session(
    region_name='us-west-2',
    profile_name='development'
)

# Create manager with the custom session
mgr = ExtensionManager(session=session)

# Register and bootstrap extensions as normal
# ...

# Now create clients using your session
ddb = session.client('dynamodb')  # Enhanced client