boto3 assist
Note: This library is in beta and subject to changes before its initial 1.0.0 release.
This library was created to make life a little easier when using boto3. It provides higher-level abstractions and utilities for common AWS operations.
Features
Core Capabilities
- DynamoDB Model Mapping - Lightweight ORM-style mapping for Python objects to DynamoDB items with comprehensive docstrings
- Session Management - Simplified session management for local, dev, and production environments
- Key Generation - Automatic primary and sort key generation for DynamoDB
- S3 Operations - Simplified S3 bucket and object operations
- Cognito Integration - User authentication and management helpers
- Error Handling - Comprehensive exception hierarchy with 20+ specific exception types
- Configuration Management - Centralized, type-safe configuration system with environment variable support
Quality & Developer Experience
- ✅ 231 passing tests with pytest and 55% code coverage
- ✅ Type hints for better IDE support (PEP 561 compliant, improvements in progress)
- ✅ Google-style docstrings with 40+ practical examples across all core DynamoDB methods
- ✅ Pre-commit hooks for automated code quality (isort, black, flake8)
- ✅ CI/CD pipeline with GitHub Actions testing on Python 3.11, 3.12, and 3.13
- ✅ Comprehensive documentation for error handling, configuration, and security best practices
Installation
Requirements: Python 3.11 or higher
pip install boto3-assist
Quick Start
DynamoDB Model Mapping
from boto3_assist.dynamodb import DynamoDB, DynamoDBModelBase
class User(DynamoDBModelBase):
def __init__(self, user_id: str, email: str, name: str):
self.user_id = user_id
self.email = email
self.name = name
def pk(self) -> str:
return f"USER#{self.user_id}"
def sk(self) -> str:
return f"PROFILE#{self.user_id}"
# Save a user
db = DynamoDB(table_name="my-table")
user = User(user_id="123", email="user@example.com", name="John Doe")
db.save(user)
# Retrieve a user
retrieved_user = db.get(User, pk="USER#123", sk="PROFILE#123")
Session Management
from boto3_assist import Boto3Session
# Lazy-loaded session that works with python-dotenv
session = Boto3Session()
dynamodb = session.resource('dynamodb')
Documentation
Core Documentation
- Configuration Guide - Centralized configuration management with environment variables
- Error Handling - 20+ specific exception types with error codes and structured details
- Security Best Practices - Security guidelines and vulnerability reporting
Examples & Guides
- DynamoDB Examples - CRUD operations, batch operations, transactions, conditional writes, and more
- S3 Examples - Bucket and object operations
- Cognito Examples - User authentication and management
- CloudWatch Examples - Log reporting and metrics
Development Documentation
- Progress Tracking - Detailed progress on architectural improvements
- Breaking Changes - Log of breaking changes (currently: Python 3.11+ requirement)
- Type Hints Progress - Type hint improvement tracking
Development
Setup Development Environment
# Clone the repository
git clone https://github.com/geekcafe/boto3-assist.git
cd boto3-assist
# Create virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
pip install -r requirements.dev.txt
pip install -e .
Running Tests
# Run all unit tests with coverage
pytest tests/unit/ -v --cov=src/boto3_assist --cov-report=term
# Run specific test file
pytest tests/unit/dynamodb_tests/dynamodb_test.py -v
# Run with detailed coverage report
pytest tests/unit/ -v --cov=src/boto3_assist --cov-report=term-missing
# Run pre-commit hooks
pre-commit run --all-files
Test Configuration
Tests use the moto library to mock AWS services. You'll need:
- A
.env.unittestfile at the project root (already included) - A mock AWS profile in
~/.aws/config:
[profile moto-mock-tests]
region = us-east-1
output = json
aws_access_key_id = test
aws_secret_access_key = test
Code Quality
# Run pre-commit hooks
pre-commit run --all-files
# Format code
black --line-length 100 src/ tests/ examples/
isort --profile black --line-length 100 src/ tests/ examples/
# Type checking
mypy src/boto3_assist --ignore-missing-imports
# Linting
flake8 src/ --max-line-length=100
Contributing
Contributions are welcome! Please ensure:
- All tests pass:
pytest tests/unit/ -v - Code is formatted:
black --line-length 100 src/ tests/ examples/ - Imports are sorted:
isort --profile black --line-length 100 src/ tests/ examples/ - Pre-commit hooks pass:
pre-commit run --all-files - New features include tests and documentation
- Follow existing patterns for docstrings (Google-style) and type hints
See PROGRESS.md for current development priorities.
Roadmap to 1.0.0
See PROGRESS.md for detailed progress tracking.
Completed ✅
- ✅ Quick Wins (8/8): Import organization, PEP 561 support, pre-commit hooks, security docs, GitHub Actions, pytest migration, Python 3.11+ requirement
- ✅ Error Handling: 20+ specific exception types with error codes and structured details
- ✅ Configuration Management: Centralized, type-safe configuration system
- ✅ Docstrings: Google-style docstrings with 40+ practical examples for all core DynamoDB methods
In Progress 🔄
- 🔄 Type Hints: Adding comprehensive type hints to improve IDE support (30% → 90%+ coverage)
Planned 📋
- 📋 API Simplification: Config objects for complex method parameters
- 📋 Input Validation: Pydantic schemas for runtime validation
- 📋 Test Coverage: Expand from 55% to 90%+ coverage
- 📋 Performance Benchmarks: Benchmark suite for performance tracking
- 📋 Debugging Utilities: Enhanced debugging helpers for DynamoDB operations
License
This project is licensed under the MIT License - see the LICENSE.txt file for details.
Support
- Issues: GitHub Issues
- Security: See SECURITY.md for vulnerability reporting
- PyPI: boto3-assist
1 maintainer
Release files for boto3-assist 0.65.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| boto3_assist-0.65.0.tar.gz | 413.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| boto3_assist-0.65.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 546.6 kB
Release files / boto3_assist-0.65.0.tar.gz
| Download URL | boto3_assist-0.65.0.tar.gz |
|---|---|
| Size | 413.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
413981a92498acca9b00000b51ab07c57162519730a22e089213168a723c24a2
|
|
BLAKE2b-256 checksum How to use checksums |
967f0285398ac95a322074c7f51c8b385abcba860fb1e3e8a77f7af43b2f6b06
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.2
|
Release files / boto3_assist-0.65.0-py3-none-any.whl
| Download URL | boto3_assist-0.65.0-py3-none-any.whl |
|---|---|
| Size | 133.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3e9b89cd0088e5615c7242ace42c45c8df097b33b5316aef79386d561ce0a85d
|
|
BLAKE2b-256 checksum How to use checksums |
234646cd6083d0f70c627e8c14103cf9abe62c8979d78052e6b1f56643bc0d83
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.2
|
