aspen-dynamo

Async DynamoDB table helper built on aioboto3. It wraps a DynamoDB table resource with small conveniences for key handling, pagination, and optional Pydantic model validation.

Installation

pip install aspen-dynamo

Optional extras:

pip install "aspen-dynamo[benchmark]"

Usage

Create a DynamoDBTable with a boto3 DynamoDB resource:

import aioboto3
from aspen_dynamo import DynamoDBTable

session = aioboto3.Session()

async with session.resource("dynamodb") as resource:
    table = DynamoDBTable("MyTable", "pk", resource=resource)
    item = await table.get_item(123)
    print(item)

Partition + sort key (composite key)

Pass a tuple of attribute names for a table with a partition key and sort key:

import aioboto3
from aspen_dynamo import DynamoDBTable

session = aioboto3.Session()

async with session.resource("dynamodb") as resource:
    table = DynamoDBTable("MyTable", ("pk", "sk"), resource=resource)
    item = await table.get_item(123, "v1")
    print(item)

Usage with a Pydantic model

Provide a model to coerce DynamoDB items into typed objects:

import aioboto3
from pydantic import BaseModel
from aspen_dynamo import DynamoDBTable

class Widget(BaseModel):
    pk: int
    name: str

session = aioboto3.Session()

async with session.resource("dynamodb") as resource:
    table = DynamoDBTable("MyTable", "pk", resource=resource, model=Widget)
    widget = await table.get_item(123)
    print(widget.name)

Benchmark

The benchmark.py script compares aspen-dynamo to other async DynamoDB clients. It uses the same DynamoDBTable API as above:

python -m aspen_dynamo.benchmark MyTable pk 123

Results from two runs:

• uvloop 0.19.0
• aioboto3 13.0.0
• aiobotocore 2.13.0
• aiodynamo 24.7
• aiohttp 3.9.5
• boto3 1.34.106
• httpx 0.28.1