Dataclass integration

Use Python dataclasses with DynamoDB. No extra dependencies needed - dataclasses are built into Python 3.7+.

Key features

• Zero dependencies (dataclasses are built-in)
• Simple and lightweight
• Works with existing dataclasses
• All pydynox methods available

Getting started

Basic usage

Use the @dynamodb_model decorator on a dataclass:

"""Basic dataclass integration example."""

from dataclasses import dataclass

from pydynox import DynamoDBClient, dynamodb_model

# Create a client
client = DynamoDBClient(region="us-east-1")


# Define your dataclass with the decorator
@dynamodb_model(table="users", hash_key="pk", range_key="sk", client=client)
@dataclass
class User:
    pk: str
    sk: str
    name: str
    age: int = 0


# Create and save
user = User(pk="USER#1", sk="PROFILE", name="John", age=30)
user.save()

# Get by key
user = User.get(pk="USER#1", sk="PROFILE")
print(user.name)  # John

# Update
user.update(name="Jane", age=31)

# Delete
user.delete()

The decorator adds these methods to your dataclass:

• save() - Save to DynamoDB
• get() - Get by key
• delete() - Delete from DynamoDB
• update() - Update specific fields
• _set_client() - Set client after creation

Your dataclass works exactly as before - all dataclass features still work.

With range key

Add a range key for composite keys:

@dynamodb_model(table="users", hash_key="pk", range_key="sk", client=client)
@dataclass
class User:
    pk: str
    sk: str
    name: str

Setting client later

You can set the client after defining the model:

@dynamodb_model(table="users", hash_key="pk")
@dataclass
class User:
    pk: str
    name: str

# Later, when you have the client
client = DynamoDBClient(region="us-east-1")
User._set_client(client)

# Now you can use it
user = User.get(pk="USER#1")

Advanced

Configuration options

Alternative: from_dataclass function

If you prefer not to use decorators:

from dataclasses import dataclass
from pydynox.integrations.dataclass import from_dataclass

@dataclass
class User:
    pk: str
    sk: str
    name: str

UserDB = from_dataclass(User, table="users", hash_key="pk", range_key="sk", client=client)
user = UserDB(pk="USER#1", sk="PROFILE", name="John")
user.save()

Dataclass vs Pydantic

Choose dataclass when:

• You want zero dependencies
• You don't need validation
• Simple data structures are enough

Choose Pydantic when:

• You need validation
• You want type coercion
• You're already using Pydantic in your app

Complex types

Dataclasses work with lists and dicts:

@dynamodb_model(table="items", hash_key="pk", client=client)
@dataclass
class Item:
    pk: str
    tags: list
    metadata: dict

item = Item(
    pk="ITEM#1",
    tags=["tag1", "tag2"],
    metadata={"key": "value"}
)
item.save()

Default values

Use dataclass defaults as usual:

from dataclasses import dataclass, field

@dynamodb_model(table="users", hash_key="pk", client=client)
@dataclass
class User:
    pk: str
    name: str
    tags: list = field(default_factory=list)
    active: bool = True