s3_and_dynamodb_backend¶

S3 + DynamoDB Hybrid Backend for Versioned Artifact Management

This module provides a high-performance hybrid backend that combines Amazon S3 for binary artifact storage with DynamoDB for metadata management. This architecture delivers the best of both services: cost-effective binary storage with fast, consistent metadata operations.

Hybrid Architecture Benefits¶

The S3+DynamoDB backend addresses the limitations of single-service approaches by leveraging the strengths of both AWS services:

S3 for Binary Storage:

Cost-effective storage for large artifacts ($/GB significantly lower than DynamoDB)
Native support for large file uploads and streaming
Built-in versioning and lifecycle management capabilities
Global replication and durability (99.999999999% durability)

DynamoDB for Metadata:

Sub-millisecond query latency for artifact metadata operations
Strong consistency for read-after-write operations
ACID transactions for complex multi-item operations
Auto-scaling based on traffic patterns

Architecture Overview¶

The hybrid backend implements a clear separation of concerns:

Data Storage Layer:

S3 Bucket Structure:
s3://{bucket}/{s3_prefix}/
├── {artifact_name_1}/
│   ├── LATEST{suffix}              # Latest version binary
│   ├── 000001{suffix}              # Version 1 binary  
│   ├── 000002{suffix}              # Version 2 binary
│   └── ...

DynamoDB Table Structure:
Artifacts:
- pk="my-app", sk="LATEST"   -> Metadata for LATEST version
- pk="my-app", sk="000001"   -> Metadata for Version 1
- pk="my-app", sk="000002"   -> Metadata for Version 2

Aliases:  
- pk="__my-app-alias", sk="prod"     -> Points to version 5
- pk="__my-app-alias", sk="staging"  -> Points to version 3

Operational Workflow:

Artifact Upload: Binary content → S3, Metadata → DynamoDB
Version Creation: Copy S3 object, Create DynamoDB version record
Alias Management: Update DynamoDB alias mappings only
Content Retrieval: Query DynamoDB for S3 location, Fetch from S3
Version Listing: Query DynamoDB only (no S3 API calls needed)

Key Components¶

Repository Class:

Central management class that coordinates S3 and DynamoDB operations. Provides high-level API for artifact lifecycle management while handling the complexity of dual-service coordination.

Artifact DataClass:

Public API representation of artifact versions with integrated S3 access. Encapsulates both DynamoDB metadata and S3 content retrieval capabilities.

Alias DataClass:

Traffic routing configuration with weighted deployment support. Enables sophisticated deployment patterns including canary releases and blue/green deployments with percentage-based traffic splitting.

Performance Characteristics¶

Metadata Operations (DynamoDB):

Get artifact version: ~1-5ms latency
List artifact versions: ~5-15ms latency
Create/update alias: ~5-10ms latency
Version publishing: ~10-20ms latency

Content Operations (S3):

Small artifacts (<1MB): ~50-200ms latency
Large artifacts (>100MB): Depends on bandwidth
Concurrent downloads: Scales horizontally

Cost Optimization:

DynamoDB: Pay only for metadata operations (minimal storage cost)
S3: Cost-effective storage for any artifact size
Combined: ~60-80% cost reduction vs DynamoDB-only for large artifacts

Deployment Patterns¶

Blue/Green Deployments:

# Deploy new version
repo.publish_artifact_version("my-app")  # Creates version 6

# Instant switch to new version
repo.put_alias("my-app", "prod", version=6)

Canary Releases:

# Route 20% traffic to new version
repo.put_alias(
    name="my-app", 
    alias="prod", 
    version=5,                    # 80% traffic
    secondary_version=6,          # 20% traffic  
    secondary_version_weight=20
)

Rollback:

# Instant rollback to previous version
repo.put_alias("my-app", "prod", version=5)

Consistency and Reliability¶

Strong Consistency:

DynamoDB provides strong consistency for all metadata operations
S3 provides eventual consistency but with read-after-write consistency for new objects
Metadata operations are immediately consistent across all clients

Error Handling:

Automatic retry logic for transient failures
Graceful degradation when services are unavailable
Comprehensive exception handling with detailed error context

Data Integrity:

SHA256 content hashing for deduplication and verification
Atomic operations where possible to prevent partial state
Soft deletion to prevent accidental data loss

class versioned.s3_and_dynamodb_backend.Artifact(name: str, version: str, update_at: datetime, s3uri: str, sha256: str)[source]¶

Public API representation of a versioned artifact with integrated S3 access.

This is the safe, user-facing interface for working with artifact versions. It provides a clean abstraction over the underlying storage systems while preventing direct access to internal DynamoDB ORM objects that could cause data corruption if misused.

Public API vs Internal ORM Distinction:

This class (Public API): Safe for end users, provides controlled access to artifact data
dynamodb.Artifact (Internal ORM): Direct DynamoDB model, used internally by Repository
User Safety: End users should only work with this dataclass, never the ORM directly

The Repository class internally uses Artifact ORM objects for DynamoDB operations, then converts them to this safe public interface. This prevents users from accidentally corrupting data through direct ORM manipulation.

Parameters:

name – Artifact name identifier
version – Version identifier (“LATEST”, “1”, “2”, etc.)
update_at – UTC timestamp when this artifact version was last modified
s3uri – Complete S3 URI where the binary content is stored
sha256 – SHA256 hash of the binary content for integrity verification

Usage Examples:

# Safe public API usage (recommended)
artifact = repo.get_artifact_version("my-app", version=5)

# Access metadata safely
print(f"Version {artifact.version} updated at {artifact.update_at}")
print(f"Content hash: {artifact.sha256}")
print(f"Stored at: {artifact.s3uri}")

# Download content with session management
content = artifact.get_content(bsm)

# Access S3 path for advanced operations
s3path = artifact.s3path
metadata = s3path.head_object(bsm=bsm).metadata

Warning

Never directly instantiate or modify Artifact ORM objects. Always use Repository methods that return this safe public API class instead.

See also

Alias for internal ORM implementation details

property s3path_version: S3Path¶

Get S3Path object for the primary artifact version.

Provides access to the full S3Path API for the primary version that this alias points to. Use this for advanced S3 operations on the primary artifact version.

Returns:: S3Path instance pointing to primary artifact version

Usage Examples:

# Check if primary version exists
exists = alias.s3path_version.exists()

# Get primary version metadata
metadata = alias.s3path_version.head_object().metadata

# Copy primary version
alias.s3path_version.copy_to("s3://backup/")

get_version_content(bsm: BotoSesManager) → bytes[source]¶

Download the binary content of the primary artifact version.

Always returns the content of the primary version, ignoring any traffic splitting configuration. Use random_artifact() if you need traffic-weighted selection.

Parameters:: bsm – Boto session manager for AWS credentials and configuration
Returns:: Complete binary content of the primary artifact version

Usage Examples:

# Always get primary version content
content = alias.get_version_content(bsm)

# For traffic-weighted selection:
selected_uri = alias.random_artifact()
if selected_uri == alias.version_s3uri:
    content = alias.get_version_content(bsm)
else:
    content = alias.get_secondary_version_content(bsm)

property s3path_secondary_version: S3Path¶

Get S3Path object for the secondary artifact version.

Provides access to the full S3Path API for the secondary version in traffic splitting configurations. Returns None if no secondary version is configured.

Returns:: S3Path instance pointing to secondary artifact version
Raises:: ValueError – If no secondary version is configured

Usage Examples:

# Check if secondary version is configured
if alias.secondary_version:
    # Get secondary version S3 path
    s3path = alias.s3path_secondary_version
    exists = s3path.exists()

get_secondary_version_content(bsm: BotoSesManager) → bytes[source]¶

Download the binary content of the secondary artifact version.

Returns the content of the secondary version used in traffic splitting. Only available when secondary_version is configured.

Parameters:: bsm – Boto session manager for AWS credentials and configuration
Returns:: Complete binary content of the secondary artifact version
Raises:: ValueError – If no secondary version is configured

Usage Examples:

# Check if secondary version exists before accessing
if alias.secondary_version:
    secondary_content = alias.get_secondary_version_content(bsm)
else:
    print("No secondary version configured")

random_artifact() → str[source]¶

Randomly select artifact version S3 URI based on traffic weights.

Implements weighted random selection for traffic splitting between primary and secondary versions. This is the core method for canary deployments and A/B testing scenarios.

Returns:: S3 URI of selected artifact version (primary or secondary)

Traffic Distribution:

No Secondary Version: Always returns primary version URI
With Secondary Version: Random selection based on weights
- Primary gets (100 - secondary_version_weight)% chance
- Secondary gets secondary_version_weight% chance

Usage Examples:

# Simple canary deployment (20% new, 80% stable)
alias = repo.put_alias(
    "my-app", "prod",
    version=5,                    # Stable - 80% traffic
    secondary_version=6,          # Canary - 20% traffic
    secondary_version_weight=20
)

# Random selection for each request
selected_uri = alias.random_artifact()
content = S3Path(selected_uri).read_bytes(bsm=bsm)

# Simulate 1000 requests to verify distribution
primary_count = sum(
    1 for _ in range(1000)
    if alias.random_artifact() == alias.version_s3uri
)
# primary_count should be approximately 800

Note

Each call produces an independent random selection. For consistent routing within a session, cache the result of this method.

class versioned.s3_and_dynamodb_backend.Repository(aws_region: str, s3_bucket: str, s3_prefix: str = 'versioned-artifacts', dynamodb_table_name: str = 'versioned-artifacts', suffix: str = '')[source]¶

Central management class for S3+DynamoDB hybrid artifact repository.

Coordinates operations between S3 (binary storage) and DynamoDB (metadata) to provide a unified, high-performance artifact management system. Handles the complexity of dual-service coordination while presenting a clean, intuitive API for artifact lifecycle management.

The Repository class is the primary entry point for all artifact operations including uploading, versioning, aliasing, and retrieval. It automatically manages the optimal distribution of data between S3 and DynamoDB based on the nature of each operation.

Parameters:

aws_region – AWS region where both S3 bucket and DynamoDB table are located
s3_bucket – S3 bucket name for binary artifact storage
s3_prefix – S3 key prefix (folder path) for organizing artifacts
dynamodb_table_name – DynamoDB table name for metadata storage
suffix – File extension suffix for artifact binaries (e.g., “.zip”, “.tar.gz”)

Architecture Overview:

S3 Storage: s3://{s3_bucket}/{s3_prefix}/ contains artifact binaries
DynamoDB Metadata: {dynamodb_table_name} contains version tracking and aliases
Coordination: Repository ensures consistency between both storage layers

Session Management:

Most Repository methods accept an optional bsm (BotoSesManager) parameter for explicit AWS credential and session management. When bsm is provided, it overrides the global session configuration established by bootstrap().

Default Behavior: Uses global boto session configured via bootstrap
Explicit Session: Pass bsm parameter to use specific credentials/configuration
Bootstrap Requirement: Call bootstrap() once before first use to bind s3pathlib and pynamodb libraries to the appropriate boto session

Usage Examples:

# Initialize repository
repo = Repository(
    aws_region="us-east-1",
    s3_bucket="my-artifacts",
    s3_prefix="versioned-artifacts",
    dynamodb_table_name="artifact-metadata"
)

# Bootstrap AWS resources (run once to bind libraries)
repo.bootstrap(bsm)

# Upload new artifact version (uses global session)
artifact = repo.put_artifact("my-app", content=binary_data)

# Create immutable version with explicit session
version = repo.publish_artifact_version("my-app", bsm=custom_bsm)

# Create production alias
alias = repo.put_alias("my-app", "prod", version=version.version)

# Retrieve via alias with explicit session
prod_artifact = repo.get_alias("my-app", "prod", bsm=bsm)
content = prod_artifact.get_version_content(bsm)

Key Features:

Automatic Deduplication: SHA256-based content deduplication across versions
Soft Deletion: Safe deletion with recovery capabilities
Traffic Splitting: Weighted routing for canary deployments
Atomic Operations: Consistent state management across S3 and DynamoDB
Cost Optimization: Efficient data placement for minimal storage costs
Session Flexibility: Support for both global and explicit session management

Note

The Repository requires both S3 and DynamoDB permissions. Use the bootstrap() method to create necessary AWS resources and bind the underlying libraries to your boto session automatically.

property s3dir_artifact_store: S3Path¶

Get the root S3 directory path for the artifact repository.

Returns:: S3Path pointing to the root directory of the artifact store

get_artifact_s3path(name: str, version: str) → S3Path[source]¶

Generate S3 path for specific artifact version using consistent naming.

Constructs the complete S3 path where a specific artifact version is stored, using the repository’s naming conventions and encoding.

Parameters:

name – Artifact name identifier
version – Version identifier (“LATEST”, “1”, “2”, etc.)

Returns:

Complete S3Path to the artifact version binary

bootstrap(bsm: BotoSesManager, dynamodb_write_capacity_units: int | None = None, dynamodb_read_capacity_units: int | None = None)[source]¶

Initialize AWS resources required for the artifact repository.

Creates the S3 bucket and DynamoDB table if they don’t exist. This is a one-time setup operation that prepares the infrastructure for artifact storage and management.

Parameters:

bsm – Boto session manager for AWS credentials and configuration
dynamodb_write_capacity_units – DynamoDB write capacity (None for on-demand)
dynamodb_read_capacity_units – DynamoDB read capacity (None for on-demand)

Usage Examples:

# Bootstrap with on-demand billing (recommended)
repo.bootstrap(bsm)

# Bootstrap with provisioned capacity
repo.bootstrap(bsm,
    dynamodb_write_capacity_units=5,
    dynamodb_read_capacity_units=10
)

Note

This operation is idempotent and safe to run multiple times. Existing resources will not be modified.

put_artifact(name: str, content: bytes, content_type: str = OPT, metadata: Dict[str, str] = OPT, tags: Dict[str, str] = OPT, bsm: BotoSesManager | None = None) → Artifact[source]¶

Create or update artifact to the latest version with automatic deduplication.

Uploads binary content to S3 and creates/updates the corresponding DynamoDB metadata record. Implements SHA256-based content deduplication to avoid unnecessary uploads when content hasn’t changed.

Parameters:

name – Artifact name identifier
content – Binary artifact content to upload
content_type – MIME content type for S3 object (e.g., “application/zip”)
metadata – Additional S3 object metadata key-value pairs
tags – S3 object tags for categorization and billing
bsm – Optional boto session manager for explicit AWS credentials/configuration. If None, uses the global session established by bootstrap

Returns:

Public API Artifact object with integrated S3 access capabilities

Usage Examples:

# Basic artifact upload
artifact = repo.put_artifact("my-app", binary_content)

# Upload with content type and metadata
artifact = repo.put_artifact(
    name="my-app",
    content=zip_content,
    content_type="application/zip",
    metadata={"build_id": "12345", "environment": "production"},
    tags={"team": "backend", "project": "api"}
)

# Upload with explicit session
artifact = repo.put_artifact("my-app", content, bsm=custom_bsm)

Note

Content deduplication uses SHA256 hashing. If content hasn’t changed, only the timestamp is updated, avoiding unnecessary S3 uploads.

get_artifact_version(name: str, version: int | str | None = None, bsm: BotoSesManager | None = None) → Artifact[source]¶

Retrieve detailed information about a specific artifact version.

Fetches artifact metadata from DynamoDB and constructs a public API Artifact object with integrated S3 access capabilities. Returns the LATEST version by default when no version is specified.

Parameters:

name – Artifact name identifier
version – Specific version to retrieve (int, str, or None for LATEST)
bsm – Optional boto session manager for explicit AWS credentials/configuration. If None, uses the global session established by bootstrap

Returns:

Public API Artifact object with metadata and S3 content access

Raises:

ArtifactNotFoundError – If artifact or version doesn’t exist or is deleted

Usage Examples:

# Get latest version
artifact = repo.get_artifact_version("my-app")

# Get specific numbered version
artifact = repo.get_artifact_version("my-app", version=5)

# Get version with explicit session
artifact = repo.get_artifact_version("my-app", version="3", bsm=custom_bsm)

# Access artifact properties
print(f"Version: {artifact.version}")
print(f"Updated: {artifact.update_at}")
print(f"SHA256: {artifact.sha256}")
print(f"S3 URI: {artifact.s3uri}")

# Download content
content = artifact.get_content(bsm)

list_artifact_versions(name: str, bsm: BotoSesManager | None = None) → List[Artifact][source]¶

Retrieve all versions of an artifact in descending order by version number.

Queries DynamoDB for all non-deleted versions of the specified artifact. Returns a list ordered from newest to oldest, with LATEST always appearing first if it exists.

Parameters:

name – Artifact name identifier to list versions for
bsm – Optional boto session manager for explicit AWS credentials/configuration. If None, uses the global session established by bootstrap

Returns:

List of public API Artifact objects ordered by version (newest first)

Usage Examples:

# List all versions of an artifact
versions = repo.list_artifact_versions("my-app")

# Access version information
for artifact in versions:
    print(f"Version {artifact.version}: {artifact.update_at}")

# List versions with explicit session
versions = repo.list_artifact_versions("my-app", bsm=custom_bsm)

# Get latest and previous version
if len(versions) >= 2:
    latest = versions[0]  # Always LATEST if it exists
    previous = versions[1]  # Most recent numbered version

Note

Only returns non-deleted versions. Soft-deleted versions are excluded from the results.

publish_artifact_version(name: str, bsm: BotoSesManager | None = None) → Artifact[source]¶

Create an immutable numbered version from the current LATEST artifact.

Performs a server-side copy in S3 from LATEST to a new numbered version and creates the corresponding DynamoDB metadata record. This creates a permanent, immutable snapshot that can be used for deployments and rollbacks.

Parameters:

name – Artifact name identifier to publish version for
bsm – Optional boto session manager for explicit AWS credentials/configuration. If None, uses the global session established by bootstrap

Returns:

Public API Artifact object representing the newly created version

Raises:

ArtifactNotFoundError – If no LATEST version exists for the artifact

Usage Examples:

# Create version 1 from LATEST
version = repo.publish_artifact_version("my-app")
print(f"Created version: {version.version}")

# Publish version with explicit session
version = repo.publish_artifact_version("my-app", bsm=custom_bsm)

# Typical deployment workflow
# 1. Upload new content to LATEST
artifact = repo.put_artifact("my-app", new_content)

# 2. Create immutable version
version = repo.publish_artifact_version("my-app")

# 3. Deploy to production
repo.put_alias("my-app", "prod", version=version.version)

Note

Versions are automatically numbered sequentially starting from 1. The version number is determined by incrementing the highest existing numbered version.

delete_artifact_version(name: str, version: int | str | None = None, bsm: BotoSesManager | None = None)[source]¶

Soft delete a specific artifact version by marking it as deleted.

Marks the artifact version as deleted in DynamoDB without removing the actual S3 binary or DynamoDB item. Soft-deleted versions become invisible to get_artifact_version and list_artifact_versions operations but can be recovered if needed.

Parameters:

name – Artifact name identifier
version – Specific version to delete (int, str, or None for LATEST)
bsm – Optional boto session manager for explicit AWS credentials/configuration. If None, uses the global session established by bootstrap

Usage Examples:

# Soft delete latest version
repo.delete_artifact_version("my-app")

# Soft delete specific version
repo.delete_artifact_version("my-app", version=5)

# Delete with explicit session
repo.delete_artifact_version("my-app", version="3", bsm=custom_bsm)

Note

This is a soft delete operation. The S3 binary and DynamoDB record remain intact but marked as deleted. Use purge_artifact for permanent deletion if needed.

list_artifact_names(bsm: BotoSesManager | None = None) → List[str][source]¶

Retrieve all artifact names available in this repository.

Scans the S3 bucket directory structure to identify all artifact names that have been uploaded to the repository. This provides a high-level view of all artifacts without listing individual versions.

Parameters:: bsm – Optional boto session manager for explicit AWS credentials/configuration. If None, uses the global session established by bootstrap
Returns:: List of artifact name strings found in the repository

Usage Examples:

# List all artifact names
names = repo.list_artifact_names()
print(f"Found {len(names)} artifacts: {names}")

# List names with explicit session
names = repo.list_artifact_names(bsm=custom_bsm)

# Iterate through all artifacts
for name in repo.list_artifact_names():
    versions = repo.list_artifact_versions(name)
    print(f"{name}: {len(versions)} versions")

Note

This method scans the S3 directory structure, so it may be slower for repositories with many artifacts compared to DynamoDB-based queries.

Create or update an alias pointing to artifact version(s) with optional traffic splitting.

Creates a named alias that can point to a single version or split traffic between two versions for advanced deployment patterns like canary releases and blue/green deployments. Validates that target versions exist before creating the alias.

Parameters:

name – Artifact name identifier the alias belongs to
alias – Alias name identifier (cannot contain hyphens due to DynamoDB constraints)
version – Primary version to point to (int, str, or None for LATEST)
secondary_version – Optional secondary version for traffic splitting
secondary_version_weight – Percentage (0-99) of traffic routed to secondary version
bsm – Optional boto session manager for explicit AWS credentials/configuration. If None, uses the global session established by bootstrap

Returns:

Public API Alias object with traffic splitting configuration

Raises:

ValueError – If alias contains hyphens, traffic weight is invalid, or versions are identical
TypeError – If secondary_version_weight is not an integer
ArtifactNotFoundError – If target version(s) don’t exist

Usage Examples:

# Simple alias pointing to latest
alias = repo.put_alias("my-app", "prod")

# Alias pointing to specific version
alias = repo.put_alias("my-app", "prod", version=5)

# Canary deployment with 20% traffic to new version
alias = repo.put_alias(
    name="my-app",
    alias="prod",
    version=5,                    # 80% traffic
    secondary_version=6,          # 20% traffic
    secondary_version_weight=20
)

# Blue/green deployment preparation
alias = repo.put_alias("my-app", "staging", version=6)  # Test on staging
alias = repo.put_alias("my-app", "prod", version=6)     # Switch production

# Create alias with explicit session
alias = repo.put_alias("my-app", "prod", version=5, bsm=custom_bsm)

Note

Alias names cannot contain hyphens due to DynamoDB key encoding constraints. Use underscores or camelCase for multi-word aliases.

get_alias(name: str, alias: str, bsm: BotoSesManager | None = None) → Alias[source]¶

Retrieve detailed information about a specific artifact alias.

Fetches alias configuration from DynamoDB and constructs a public API Alias object with traffic splitting details and S3 access capabilities for both primary and secondary versions if configured.

Parameters:

name – Artifact name identifier the alias belongs to
alias – Alias name identifier to retrieve
bsm – Optional boto session manager for explicit AWS credentials/configuration. If None, uses the global session established by bootstrap

Returns:

Public API Alias object with version details and S3 access

Raises:

AliasNotFoundError – If the alias doesn’t exist

Usage Examples:

# Get simple alias
alias = repo.get_alias("my-app", "prod")
print(f"Production points to version: {alias.version}")

# Get alias with traffic splitting
alias = repo.get_alias("my-app", "canary")
if alias.secondary_version:
    print(f"Traffic split: {alias.version} ({100-alias.secondary_version_weight}%) "
          f"and {alias.secondary_version} ({alias.secondary_version_weight}%)")

# Get alias with explicit session
alias = repo.get_alias("my-app", "prod", bsm=custom_bsm)

# Use alias for content access
content = alias.get_version_content(bsm)  # Always primary version
selected_uri = alias.random_artifact()    # Traffic-weighted selection

list_aliases(name: str, bsm: BotoSesManager | None = None) → List[Alias][source]¶

Retrieve all aliases configured for a specific artifact.

Queries DynamoDB for all aliases associated with the specified artifact and constructs a list of public API Alias objects with complete traffic splitting configurations and S3 access capabilities.

Parameters:

name – Artifact name identifier to list aliases for
bsm – Optional boto session manager for explicit AWS credentials/configuration. If None, uses the global session established by bootstrap

Returns:

List of public API Alias objects for the artifact

Usage Examples:

# List all aliases for an artifact
aliases = repo.list_aliases("my-app")
for alias in aliases:
    print(f"Alias {alias.alias} -> version {alias.version}")

# List aliases with explicit session
aliases = repo.list_aliases("my-app", bsm=custom_bsm)

# Check for specific deployment patterns
for alias in repo.list_aliases("my-app"):
    if alias.secondary_version:
        print(f"Canary: {alias.alias} splitting traffic between "
              f"v{alias.version} and v{alias.secondary_version}")
    else:
        print(f"Single: {alias.alias} -> v{alias.version}")

Note

Returns all aliases regardless of their traffic splitting configuration. Check the secondary_version field to determine if traffic splitting is active.

delete_alias(name: str, alias: str, bsm: BotoSesManager | None = None)[source]¶

Permanently delete an alias from the repository.

Removes the alias record from DynamoDB completely. This is a hard delete operation that cannot be undone. The underlying artifact versions and S3 objects remain intact and unaffected.

Parameters:

name – Artifact name identifier the alias belongs to
alias – Alias name identifier to delete
bsm – Optional boto session manager for explicit AWS credentials/configuration. If None, uses the global session established by bootstrap

Usage Examples:

# Delete production alias
repo.delete_alias("my-app", "prod")

# Delete with explicit session
repo.delete_alias("my-app", "staging", bsm=custom_bsm)

# Safe cleanup workflow
# 1. First redirect traffic to a safe version
repo.put_alias("my-app", "prod", version="stable_version")

# 2. Then delete the problematic alias
repo.delete_alias("my-app", "canary")

Warning

This is a permanent deletion. The alias configuration including any traffic splitting setup will be completely lost and cannot be recovered.

purge_artifact_versions(name: str, keep_last_n: int = 10, purge_older_than_secs: int = 7776000, bsm: BotoSesManager | None = None) → Tuple[datetime, List[Artifact]][source]¶

Selectively soft-delete old artifact versions based on retention policies.

Applies retention rules to automatically clean up old versions while preserving recent versions and the LATEST version. Uses both count-based and age-based retention criteria to determine which versions to soft-delete.

Parameters:

name – Artifact name identifier to purge versions for
keep_last_n – Minimum number of recent versions to preserve (default: 10)
purge_older_than_secs – Age threshold in seconds for purging (default: 90 days)
bsm – Optional boto session manager for explicit AWS credentials/configuration. If None, uses the global session established by bootstrap

Returns:

Tuple of (purge_timestamp, list_of_deleted_artifacts)

Retention Logic:

A version is soft-deleted if ALL of the following conditions are met:

Version is NOT in the most recent keep_last_n versions
Version is older than purge_older_than_secs seconds
Version is NOT the LATEST version (always preserved)

Usage Examples:

# Use default retention (keep 10 recent, purge >90 days)
purge_time, deleted = repo.purge_artifact_versions("my-app")
print(f"Purged {len(deleted)} versions at {purge_time}")

# Custom retention policy (keep 5 recent, purge >30 days)
purge_time, deleted = repo.purge_artifact_versions(
    name="my-app",
    keep_last_n=5,
    purge_older_than_secs=30 * 24 * 60 * 60  # 30 days
)

# Aggressive cleanup (keep only 3 recent, purge >7 days)
purge_time, deleted = repo.purge_artifact_versions(
    "my-app", keep_last_n=3, purge_older_than_secs=7*24*60*60, bsm=custom_bsm
)

Note

This performs soft deletion only. Use purge_artifact for permanent deletion of all artifact data including S3 binaries.

purge_artifact(name: str, bsm: BotoSesManager | None = None)[source]¶

Permanently delete all versions and aliases for a specific artifact.

Performs complete cleanup by removing all S3 binaries, DynamoDB metadata records, and alias configurations for the specified artifact. This is an irreversible hard delete operation.

Parameters:

name – Artifact name identifier to completely purge
bsm – Optional boto session manager for explicit AWS credentials/configuration. If None, uses the global session established by bootstrap

Usage Examples:

# Permanently delete all data for an artifact
repo.purge_artifact("my-app")

# Delete with explicit session
repo.purge_artifact("my-app", bsm=custom_bsm)

# Safe deletion workflow
# 1. First ensure no aliases point to this artifact
aliases = repo.list_aliases("my-app")
for alias in aliases:
    repo.delete_alias("my-app", alias.alias)

# 2. Then purge the artifact completely
repo.purge_artifact("my-app")

Danger

This operation is IRREVERSIBLE. All versions, aliases, metadata, and S3 binaries for this artifact will be permanently destroyed. Ensure no systems depend on this artifact before deletion.

purge_all(bsm: BotoSesManager | None = None)[source]¶

Permanently delete ALL artifacts and aliases in the entire repository.

Performs complete repository cleanup by removing all S3 content and DynamoDB data. This destroys the entire repository content while leaving the AWS resources (bucket, table) intact for future use.

Parameters:: bsm – Optional boto session manager for explicit AWS credentials/configuration. If None, uses the global session established by bootstrap

Usage Examples:

# Nuclear option - delete everything (typically for testing)
repo.purge_all()

# Purge with explicit session
repo.purge_all(bsm=custom_bsm)

# Repository reset workflow
# 1. Backup critical data if needed
important_artifacts = ["critical-app", "backup-service"]
for name in important_artifacts:
    artifact = repo.get_artifact_version(name)
    # ... backup logic ...

# 2. Purge everything
repo.purge_all()

# 3. Repository is now empty but ready for new artifacts

Danger

This operation is IRREVERSIBLE and destroys ALL artifacts, versions, aliases, and metadata in the repository. Only use for testing or complete repository decommissioning.