Type annotations for boto3 DynamoDB

1.42.73 · active · verified Sat Apr 11

types-boto3-dynamodb provides comprehensive type annotations for the `boto3` AWS SDK's DynamoDB service. It is part of the `types-boto3` project and is generated by `mypy-boto3-builder` 8.12.0. These stubs enhance developer experience by enabling static type checking, autocompletion, and improved readability for `boto3` interactions with DynamoDB, compatible with tools like VSCode, PyCharm, mypy, and pyright. The library is actively maintained with frequent updates to align with new `boto3` versions and Python features.

Warnings

breaking Python 3.8 support has been removed. `types-boto3-dynamodb` and its builder `mypy-boto3-builder` now require Python 3.9 or newer.
Fix: Upgrade your Python environment to 3.9 or higher.
breaking The project migrated to PEP 561 compliant packages. This might require adjustments in how some build systems or advanced type checker configurations resolve imports, though direct usage often remains compatible.
Fix: Ensure your type checker (e.g., mypy, pyright) is up-to-date and configured to correctly resolve PEP 561 packages. Most users should not encounter issues with standard setups.
breaking TypeDef naming conventions were changed for some packed method arguments and conflicting names (e.g., `CreateDistributionRequestRequestTypeDef` became `CreateDistributionRequestTypeDef`). If you directly reference these generated TypedDicts, your code may break.
Fix: Review your code for direct imports or usage of generated TypedDicts and update their names according to the new conventions, referring to the latest generated documentation or code completions.
gotcha For optimal production environments, it is recommended to conditionally import type hints using `if TYPE_CHECKING:` to prevent adding the stub package as a runtime dependency. This avoids potential `pylint` warnings if not handled correctly.
Fix: Wrap type stub imports and annotations with `if TYPE_CHECKING: ... else: ...` blocks. For example: `if TYPE_CHECKING: from types_boto3_dynamodb import DynamoDBClient else: DynamoDBClient = object`.
gotcha PyCharm users might experience slow performance and high CPU usage, especially with `Literal` overloads. This is a known issue (PY-40997) within PyCharm's type checker.
Fix: Consider using `types-boto3-lite` (a leaner version of stubs) if available for your service, or disable PyCharm's built-in type checker and rely on external tools like mypy or pyright instead for type checking.
gotcha The overarching project name for boto3 type stubs has transitioned from `boto3-stubs` to `types-boto3`. While `types-boto3-dynamodb` remains the specific package for DynamoDB, users migrating from older setups or referencing older documentation should be aware of this change.
Fix: Prefer `types-boto3` and its specific service packages (like `types-boto3-dynamodb`) in new projects and when updating dependencies. Update any `boto3-stubs` references in `install_requires` or similar configurations.

Install

pip install 'types-boto3[dynamodb]' Recommended (as part of types-boto3 bundle)
pip install types-boto3-dynamodb Standalone DynamoDB stubs

Imports

DynamoDBClient
```
from types_boto3_dynamodb import DynamoDBClient
```
Type for the low-level DynamoDB client.
DynamoDBServiceResource
```
from types_boto3_dynamodb import DynamoDBServiceResource
```
Type for the high-level DynamoDB service resource.

Table

from types_boto3_dynamodb.service_resource import Table

Type for a DynamoDB Table resource object.

ArchivalSummaryTypeDef
```
from types_boto3_dynamodb.type_defs import ArchivalSummaryTypeDef
```
Example of importing a specific TypedDict for DynamoDB operation parameters/responses.

Quickstart

This quickstart demonstrates how to obtain type-hinted DynamoDB clients, service resources, and table resources using `types-boto3-dynamodb`. It leverages `typing.TYPE_CHECKING` to ensure the type stubs are only used during static analysis, preventing runtime dependencies in production. The `boto3` library must be installed alongside these type stubs for full functionality.

import boto3
from typing import TYPE_CHECKING

if TYPE_CHECKING:
    from types_boto3_dynamodb import DynamoDBClient, DynamoDBServiceResource
    from types_boto3_dynamodb.service_resource import Table


def get_dynamodb_client() -> 'DynamoDBClient':
    """Returns a type-hinted DynamoDB client."""
    return boto3.client('dynamodb')


def get_dynamodb_resource() -> 'DynamoDBServiceResource':
    """Returns a type-hinted DynamoDB service resource."""
    return boto3.resource('dynamodb')


def get_table(table_name: str) -> 'Table':
    """Returns a type-hinted DynamoDB Table resource."""
    dynamodb_resource: DynamoDBServiceResource = get_dynamodb_resource()
    return dynamodb_resource.Table(table_name)

# Example usage (without actual AWS calls):
client = get_dynamodb_client()
print(f"DynamoDB client type: {type(client)}")

resource = get_dynamodb_resource()
print(f"DynamoDB resource type: {type(resource)}")

# You would typically interact with a real table here
# table = get_table("YourTableName")
# print(f"DynamoDB table type: {type(table)}")

view raw JSON →