s3_only_backend¶

S3-Only Backend for Versioned Artifact Management

This module provides a comprehensive S3-based backend for storing and managing versioned artifacts with alias support, enabling sophisticated deployment patterns like blue/green deployments, canary releases, and rollbacks.

What is S3-Only Backend?¶

The S3-Only Backend is a storage system that uses Amazon S3 as the sole backend for artifact versioning and alias management. Unlike hybrid approaches that combine S3 with DynamoDB, this backend stores all metadata and version information directly in S3 using a structured folder hierarchy and JSON files.

S3 Folder Structure¶

The backend organizes artifacts in S3 using the following hierarchical structure:

s3://{bucket}/{s3_prefix}/      # <--- this is a Repository
├── {artifact_name_1}/          # <--- this is an Artifact
│   ├── versions/               # <--- contains all versions of the artifact
│   │   ├── 000000_LATEST{suffix}          # Latest version (always first)
│   │   ├── 999999_000001{suffix}          # Version 1 (reverse sorted)
│   │   ├── 999998_000002{suffix}          # Version 2
│   │   ├── 999997_000003{suffix}          # Version 3
│   │   └── ...
│   └── aliases/                # <--- contains alias JSON files
│       ├── prod.json                      # Production alias
│       ├── staging.json                   # Staging alias
│       └── ...
├── {artifact_name_2}/
│   ├── versions/
│   └── aliases/
└── ...

Key Structure Components:¶

Root Directory: s3://{bucket}/{s3_prefix}/ (default: “versioned-artifacts”)
Artifact Directories: Each artifact gets its own folder named after the artifact
Versions Subdirectory: Contains all versions of the artifact binary files
Aliases Subdirectory: Contains JSON files mapping aliases to specific versions

Filename Encoding System¶

The backend uses a sophisticated filename encoding system that leverages S3’s alphabetical sorting to ensure proper version ordering:

Version Filename Format¶

LATEST version: 000000_LATEST{suffix} (always appears first in listings)
Numeric versions: {reverse_sort_key}_{zero_padded_version}{suffix}

Examples¶

Version LATEST → 000000_LATEST.zip
Version 1 → 999999_000001.zip
Version 2 → 999998_000002.zip
Version 999999 → 000001_999999.zip

The encoding ensures that:

LATEST always appears first in S3 listings
Newer versions appear before older versions
Efficient pagination and sorting without requiring metadata queries

Alias Implementation¶

Aliases are implemented as JSON files stored in the aliases/ subdirectory of each artifact. Each alias file contains comprehensive metadata about version mappings and supports advanced deployment patterns.

Alias Structure¶

Each alias JSON file contains:

{
    "name": "artifact_name",
    "alias": "prod", 
    "version": "5",
    "secondary_version": "4",
    "secondary_version_weight": 20,
    "version_s3uri": "s3://bucket/path/to/version/5",
    "secondary_version_s3uri": "s3://bucket/path/to/version/4",
    "update_at": "2024-01-01T12:00:00Z"
}

Alias Features:¶

Primary Version: The main version that the alias points to
Secondary Version (optional): Enables traffic splitting for gradual rollouts
Weight-based Routing: secondary_version_weight determines percentage of traffic routed to the secondary version (0-100)
Immutable References: Aliases contain full S3 URIs to specific artifact versions
Update Tracking: Timestamps track when aliases were last modified

Deployment Patterns Enabled¶

Blue/Green Deployments: Switch aliases between versions instantly
Canary Releases: Gradually increase traffic to new versions using weights
Rollbacks: Instantly revert to previous versions by updating alias
A/B Testing: Route percentage of traffic to different versions

Core Classes¶

The module provides several key classes:

Repository: Main interface for artifact and alias operations
Artifact: Represents a versioned artifact with metadata
Alias: Represents an alias mapping with traffic splitting support

Usage Examples¶

Repository setup:

repo = Repository(
    aws_region="us-east-1",
    s3_bucket="my-artifacts-bucket",
    suffix=".zip"
)
repo.bootstrap(bsm)

Artifact management:

# Upload and publish versions
repo.put_artifact(bsm, name="myapp", content=binary_data)
repo.publish_artifact_version(bsm, name="myapp")  # Creates version 1

# Create alias for production
repo.put_alias(bsm, name="myapp", alias="prod", version=1)

# Canary deployment with traffic splitting
repo.put_alias(
    bsm, name="myapp", alias="prod", 
    version=1, secondary_version=2, secondary_version_weight=10
)

The S3-Only Backend provides a robust, scalable solution for artifact management with native support for modern deployment practices.

versioned.s3_only_backend.encode_filename(version: int | str | None) → str[source]¶

Encode version into S3-compatible filename for proper chronological sorting.

Creates filenames that leverage S3’s alphabetical object listing to ensure versions appear in reverse chronological order (newest first). Uses a clever reverse-sorting algorithm where higher version numbers get lower alphabetical prefixes, ensuring LATEST always appears first.

The encoding scheme uses the formula: {(10^6 - version_number):06d}_{version_number:06d}

Parameters:: version – Version number to encode into filename
Returns:: Encoded filename suitable for S3 storage

Examples:

Filename encoding for chronological sorting:

encode_filename(None)      # "000000_LATEST"
encode_filename("LATEST")  # "000000_LATEST"
encode_filename(1)         # "999999_000001"
encode_filename(2)         # "999998_000002"
encode_filename(999999)    # "000001_999999"

When listed alphabetically in S3, files appear as: - 000000_LATEST (newest development) - 000001_999999 (version 999999) - 999998_000002 (version 2) - 999999_000001 (version 1, oldest)

versioned.s3_only_backend.decode_filename(version: str) → str[source]¶

Decode S3 filename back to original version string.

Reverses the encoding performed by encode_filename() to extract the original version number from the S3-compatible filename format.

Parameters:: version – Encoded filename to decode
Returns:: Original version string

Examples:

Filename decoding:

decode_filename("000000_LATEST")  # "LATEST"
decode_filename("000001_999999")  # "999999"
decode_filename("999998_000002")  # "2"
decode_filename("999999_000001")  # "1"

See also

encode_filename() for the encoding process

versioned.s3_only_backend.validate_alias_name(alias: str)[source]¶

Validate alias name according to naming convention rules.

Ensures alias names follow the required naming patterns to prevent conflicts with internal version identifiers and maintain consistency across the artifact management system.

Parameters:: alias – Alias name to validate
Raises:: ValueError – If alias name violates naming conventions

Validation Rules:

Cannot be “LATEST” (reserved for version identifier)
Cannot contain hyphens (conflicts with internal encoding)
Must start with alphabetic character

Examples:

Valid alias names:

validate_alias_name("prod")     # Valid
validate_alias_name("staging")  # Valid
validate_alias_name("v1_0")     # Valid

Invalid alias names:

validate_alias_name("LATEST")     # Raises ValueError
validate_alias_name("prod-v1")    # Raises ValueError
validate_alias_name("1_prod")     # Raises ValueError

class versioned.s3_only_backend.Base[source]¶

Base class providing common serialization functionality for data classes.

Provides standard dictionary conversion methods used by artifact and alias data classes for JSON serialization and deserialization operations.

classmethod from_dict(dct: dict)[source]¶

Create instance from dictionary representation.

Parameters:: dct – Dictionary containing field values for the data class
Returns:: New instance of the data class

to_dict() → dict[source]¶

Convert instance to dictionary representation.

Returns:: Dictionary containing all field values

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

Immutable artifact version with metadata and content access.

Represents a specific version of an artifact stored in S3, containing all necessary metadata for version identification, content integrity verification, and direct access to the stored binary data.

Parameters:

name – Artifact identifier unique within the repository
version – Version string (“LATEST” or numeric like “1”, “2”, etc.)
update_at – ISO format UTC timestamp when artifact was last modified
s3uri – Complete S3 URI pointing to the artifact binary
sha256 – SHA256 hash for content integrity verification

Examples:

Artifact representation:

{
    "name": "myapp",
    "version": "3",
    "update_at": "2024-01-01T12:00:00Z",
    "s3uri": "s3://bucket/artifacts/myapp/versions/999997_000003.zip",
    "sha256": "abc123...def789"
}

property update_datetime: datetime¶

Parse update timestamp into timezone-aware datetime object.

Returns:: Parsed datetime with UTC timezone information

property s3path: S3Path¶

Create S3Path object for direct S3 operations.

Returns:: S3Path instance for reading, copying, or inspecting the artifact

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

Download and return the complete artifact binary content.

Parameters:: bsm – AWS session manager for S3 access
Returns:: Complete binary content of the artifact
Raises:: ClientError – If artifact no longer exists in S3

class versioned.s3_only_backend.Alias(name: str, alias: str, update_at: str, version: str, secondary_version: str | None, secondary_version_weight: int | None, version_s3uri: str, secondary_version_s3uri: str | None)[source]¶

Named reference to artifact versions with traffic splitting support.

Provides stable references to specific artifact versions that enable sophisticated deployment patterns including blue/green deployments, canary releases, and gradual rollouts with weighted traffic distribution.

Parameters:

name – Artifact identifier that this alias references
alias – Human-readable alias name (cannot contain hyphens)
update_at – ISO format UTC timestamp when alias was last modified
version – Primary artifact version this alias points to
secondary_version – Optional secondary version for traffic splitting
secondary_version_weight – Percentage (0-99) of traffic routed to secondary version
version_s3uri – Complete S3 URI of the primary artifact version
secondary_version_s3uri – Complete S3 URI of the secondary artifact version

Examples:

Simple alias pointing to single version:

{
    "name": "myapp",
    "alias": "prod",
    "version": "5",
    "secondary_version": null,
    "secondary_version_weight": null,
    "version_s3uri": "s3://bucket/artifacts/myapp/versions/999995_000005.zip",
    "secondary_version_s3uri": null,
    "update_at": "2024-01-01T12:00:00Z"
}

Canary deployment with 20% traffic to new version:

{
    "name": "myapp",
    "alias": "prod",
    "version": "5",
    "secondary_version": "6",
    "secondary_version_weight": 20,
    "version_s3uri": "s3://bucket/artifacts/myapp/versions/999995_000005.zip",
    "secondary_version_s3uri": "s3://bucket/artifacts/myapp/versions/999994_000006.zip",
    "update_at": "2024-01-01T15:30:00Z"
}

property update_datetime: datetime¶

Parse update timestamp into timezone-aware datetime object.

Returns:: Parsed datetime with UTC timezone information

property s3path_version: S3Path¶

Create S3Path object for the primary artifact version.

Returns:: S3Path instance for the main version referenced by this alias

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

Download and return the primary artifact version content.

Parameters:: bsm – AWS session manager for S3 access
Returns:: Complete binary content of the primary artifact version
Raises:: ClientError – If primary artifact no longer exists in S3

property s3path_secondary_version: S3Path¶

Create S3Path object for the secondary artifact version.

Returns:: S3Path instance for the secondary version used in traffic splitting
Raises:: AttributeError – If secondary_version_s3uri is None

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

Download and return the secondary artifact version content.

Parameters:

bsm – AWS session manager for S3 access

Returns:

Complete binary content of the secondary artifact version

Raises:

ClientError – If secondary artifact no longer exists in S3
AttributeError – If secondary_version_s3uri is None

random_artifact() → str[source]¶

Select artifact version based on weighted random distribution.

Implements traffic splitting by randomly selecting between primary and secondary versions based on the configured weight distribution. Used for canary deployments and gradual rollouts.

Returns:: S3 URI of the selected artifact version

Examples:

Single version alias always returns primary:

alias.random_artifact()  # Always returns version_s3uri

Weighted distribution (80% primary, 20% secondary):

# Returns version_s3uri ~80% of the time
# Returns secondary_version_s3uri ~20% of the time
selected_uri = alias.random_artifact()

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

S3-based artifact repository with comprehensive version and alias management.

Provides a complete artifact management system using S3 as the storage backend. Supports versioned artifacts, stable aliases, traffic splitting for deployments, and automated lifecycle management with intelligent filename encoding for optimal performance.

The repository organizes artifacts in a hierarchical S3 structure that enables efficient listing, versioning, and alias management without requiring external databases or metadata stores.

Parameters:

aws_region – AWS region where the S3 bucket resides
s3_bucket – S3 bucket name for artifact storage
s3_prefix – S3 key prefix (folder path) for organizing artifacts
suffix – File extension to append to all artifact files

Examples:

Repository initialization:

repo = Repository(
    aws_region="us-east-1",
    s3_bucket="company-artifacts",
    s3_prefix="applications",
    suffix=".zip"
)

Complete workflow:

# Setup and upload
repo.bootstrap(bsm)
repo.put_artifact(bsm, "myapp", binary_data)

# Version management
v1 = repo.publish_artifact_version(bsm, "myapp")  # Creates version 1
repo.put_artifact(bsm, "myapp", new_binary_data)
v2 = repo.publish_artifact_version(bsm, "myapp")  # Creates version 2

# Alias and deployment patterns
repo.put_alias(bsm, "myapp", "prod", version=1)  # Blue/green
repo.put_alias(                                  # Canary
    bsm, "myapp", "prod", version=1,
    secondary_version=2, secondary_version_weight=10
)

Note

All artifacts are stored with SHA256 content hashing for integrity verification and automatic deduplication during publishing.

property s3dir_artifact_store: S3Path¶

Get the root S3 directory for the entire artifact repository.

Returns:: S3Path pointing to the repository root directory

Example:

Repository root structure:

s3://my-bucket/artifacts/  # s3dir_artifact_store
├── app1/
├── app2/
└── service-x/

bootstrap(bsm: BotoSesManager)[source]¶

Initialize the S3 backend by creating the bucket if it doesn’t exist.

Ensures the specified S3 bucket exists and is accessible for artifact storage. Creates the bucket with appropriate regional configuration if it doesn’t already exist.

Parameters:: bsm – AWS session manager for S3 operations
Raises:: ClientError – If bucket creation fails due to permissions or conflicts

Note

This method is idempotent - safe to call multiple times.

get_latest_published_artifact_version_number(bsm: BotoSesManager, name: str) → int[source]¶

Get the highest published version number for an artifact.

Returns the numeric version of the most recently published artifact. Returns 0 if only the LATEST version exists (no published versions yet).

Parameters:

bsm – AWS session manager for S3 operations
name – Artifact name to check

Returns:

Highest published version number, or 0 if none published

Examples:

Version progression:

repo.put_artifact(bsm, "myapp", data)  # Creates LATEST
repo.get_latest_published_version(bsm, "myapp")  # Returns 0

repo.publish_artifact_version(bsm, "myapp")  # Creates version 1
repo.get_latest_published_version(bsm, "myapp")  # Returns 1

repo.put_artifact(bsm, "myapp", new_data)  # Updates LATEST
repo.publish_artifact_version(bsm, "myapp")  # Creates version 2
repo.get_latest_published_version(bsm, "myapp")  # Returns 2

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

Upload or update the LATEST version of an artifact.

Creates or updates the mutable LATEST version with new content. If the content is identical to the existing LATEST version (based on SHA256), no upload occurs and the existing artifact metadata is returned.

This is typically the first step in the artifact workflow, followed by publish_artifact_version() to create immutable numbered versions.

Parameters:

bsm – AWS session manager for S3 operations
name – Unique artifact identifier within the repository
content – Binary artifact data to store
content_type – MIME type for S3 object (auto-detected if not provided)
metadata – Additional S3 object metadata key-value pairs
tags – S3 object tags for categorization and billing

Returns:

Artifact object with metadata for the LATEST version

Examples:

Basic artifact upload:

with open("app.zip", "rb") as f:
    artifact = repo.put_artifact(
        bsm=bsm,
        name="myapp",
        content=f.read()
    )

With metadata and content type:

artifact = repo.put_artifact(
    bsm=bsm,
    name="myapp",
    content=binary_data,
    content_type="application/zip",
    metadata={"build_id": "12345", "commit": "abc123"},
    tags={"environment": "production", "team": "backend"}
)

Note

Content deduplication is automatic - identical content won’t be re-uploaded, making this operation safe for CI/CD pipelines.

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

Retrieve metadata for a specific artifact version.

Returns comprehensive information about an artifact version including S3 location, content hash, and modification timestamps without downloading the actual binary content.

Parameters:

bsm – AWS session manager for S3 operations
name – Artifact name to retrieve
version – Specific version to get (defaults to LATEST)

Returns:

Artifact object with complete metadata

Raises:

ArtifactNotFoundError – If the specified artifact or version doesn’t exist

Examples:

Get latest version:

artifact = repo.get_artifact_version(bsm, "myapp")
print(f"Latest SHA256: {artifact.sha256}")

Get specific version:

v2 = repo.get_artifact_version(bsm, "myapp", version=2)
print(f"Version 2 S3 URI: {v2.s3uri}")
print(f"Updated: {v2.update_datetime}")

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

List all versions of an artifact in reverse chronological order.

Returns all available versions including the mutable LATEST version and all published immutable versions. The list is ordered with LATEST first, followed by numbered versions from newest to oldest.

Parameters:

bsm – AWS session manager for S3 operations
name – Artifact name to list versions for

Returns:

List of Artifact objects sorted by version (newest first)

Raises:

ArtifactNotFoundError – If the artifact doesn’t exist

Examples:

List all versions:

versions = repo.list_artifact_versions(bsm, "myapp")
for artifact in versions:
    print(f"Version {artifact.version}: {artifact.update_at}")

Output example:

Version LATEST: 2024-01-01T15:30:00Z
Version 3: 2024-01-01T14:00:00Z
Version 2: 2024-01-01T12:00:00Z
Version 1: 2024-01-01T10:00:00Z

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

Create an immutable numbered version from the current LATEST artifact.

Copies the current LATEST version to create a new numbered version that cannot be modified. If the LATEST content is identical to the most recent published version (based on SHA256), no new version is created and the existing version is returned.

This enables immutable deployments while maintaining a mutable development version in LATEST. Version numbers are automatically incremented.

Parameters:

bsm – AWS session manager for S3 operations
name – Artifact name to publish a version for

Returns:

Artifact object representing the published version

Raises:

ArtifactNotFoundError – If no LATEST version exists

Examples:

Publishing workflow:

# Upload new content
repo.put_artifact(bsm, "myapp", new_content)

# Create immutable version
v1 = repo.publish_artifact_version(bsm, "myapp")
print(f"Published version {v1.version}")  # "Published version 1"

# Update and publish again
repo.put_artifact(bsm, "myapp", newer_content)
v2 = repo.publish_artifact_version(bsm, "myapp")
print(f"Published version {v2.version}")  # "Published version 2"

No-op when content unchanged:

# If LATEST hasn't changed since last publish
same_version = repo.publish_artifact_version(bsm, "myapp")
# Returns existing version, no new version created

Note

Published versions are immutable and cannot be modified. Use delete_artifact_version() to remove unwanted versions.

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

Permanently delete a specific artifact version from S3.

Removes the specified version file from S3 storage. The LATEST version cannot be deleted using this method - use purge_artifact() to remove all versions including LATEST.

This operation is irreversible and should be used carefully, especially if the version is referenced by active aliases.

Parameters:

bsm – AWS session manager for S3 operations
name – Artifact name
version – Specific version number to delete (cannot be “LATEST”)

Raises:

ArtifactS3BackendError – If attempting to delete the LATEST version

Examples:

Delete specific versions:

# Delete old version no longer needed
repo.delete_artifact_version(bsm, "myapp", version=1)

# This will raise an error
repo.delete_artifact_version(bsm, "myapp", version="LATEST")

Warning

Deleting a version that is actively referenced by aliases may cause deployment issues. Check alias references before deletion.

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

List all artifact names stored in this repository.

Scans the repository root directory to find all artifacts that have been created. Returns just the artifact names without version information.

Parameters:: bsm – AWS session manager for S3 operations
Returns:: Sorted list of unique artifact names

Examples:

Discover all artifacts::

names = repo.list_artifact_names(bsm) print(f”Found artifacts: {names}”) # Output: [“api-service”, “frontend”, “worker-service”]

Use with other operations::

for name in repo.list_artifact_names(bsm):: latest = repo.get_artifact_version(bsm, name) print(f”{name}: {latest.version} ({latest.update_at})”)

Create or update an alias pointing to artifact versions with traffic splitting.

Creates stable references to specific artifact versions that enable sophisticated deployment patterns. Supports optional traffic splitting between a primary and secondary version for gradual rollouts and canary deployments.

Parameters:

bsm – AWS session manager for S3 operations
name – Artifact name to create alias for
alias – Human-readable alias name (cannot contain hyphens)
version – Primary version to point to (defaults to LATEST)
secondary_version – Optional secondary version for traffic splitting
secondary_version_weight – Percentage (0-99) of traffic routed to secondary

Returns:

Alias object with complete configuration

Raises:

ValueError – If alias name contains hyphens or weight is invalid
TypeError – If secondary_version_weight is not an integer
ArtifactNotFoundError – If specified versions don’t exist

Examples:

Simple alias (blue/green deployment):

# Point prod to version 5
alias = repo.put_alias(bsm, "myapp", "prod", version=5)

Canary deployment with traffic splitting:

# 80% traffic to v5, 20% to v6
alias = repo.put_alias(
    bsm, "myapp", "prod",
    version=5,
    secondary_version=6,
    secondary_version_weight=20
)

Point to latest development:

# Alias points to mutable LATEST version
alias = repo.put_alias(bsm, "myapp", "dev")

Note

Aliases are immediately active after creation. Ensure versions are thoroughly tested before updating production aliases.

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

Retrieve detailed information about a specific alias.

Returns complete alias configuration including version references, traffic splitting settings, and update timestamps.

Parameters:

bsm – AWS session manager for S3 operations
name – Artifact name
alias – Alias name to retrieve

Returns:

Alias object with complete configuration

Raises:

AliasNotFoundError – If the specified alias doesn’t exist

Examples:

Get alias configuration:

alias = repo.get_alias(bsm, "myapp", "prod")
print(f"Primary version: {alias.version}")
if alias.secondary_version:
    print(f"Secondary: {alias.secondary_version} ({alias.secondary_version_weight}%)")

Use for deployment decisions:

alias = repo.get_alias(bsm, "myapp", "prod")
selected_uri = alias.random_artifact()  # Traffic splitting
artifact_data = S3Path(selected_uri).read_bytes(bsm)

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

List all aliases configured for a specific artifact.

Returns all alias configurations for the given artifact, including their version references and traffic splitting settings.

Parameters:

bsm – AWS session manager for S3 operations
name – Artifact name to list aliases for

Returns:

List of Alias objects for the artifact

Examples:

List all aliases:

aliases = repo.list_aliases(bsm, "myapp")
for alias in aliases:
    print(f"{alias.alias}: v{alias.version}")
    if alias.secondary_version:
        print(f"  └─ Canary: v{alias.secondary_version} ({alias.secondary_version_weight}%)")

Output example:

prod: v5
  └─ Canary: v6 (20%)
staging: vLATEST
dev: vLATEST

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

Permanently delete an alias from the repository.

Removes the alias configuration file from S3. This operation is irreversible and will immediately stop routing traffic to the versions referenced by this alias.

Parameters:

bsm – AWS session manager for S3 operations
name – Artifact name
alias – Alias name to delete

Examples:

Remove obsolete aliases:

# Remove old staging alias
repo.delete_alias(bsm, "myapp", "staging_v2")

Cleanup after blue/green deployment:

# After successful deployment, remove canary
repo.put_alias(bsm, "myapp", "prod", version=6)  # Full traffic to v6
repo.delete_alias(bsm, "myapp", "canary")        # Remove canary alias

Warning

Deleting an alias that is actively used by applications will cause immediate failures. Ensure no systems depend on the alias before deletion.

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

Automatically clean up old artifact versions based on retention policies.

Removes artifact versions that don’t meet the retention criteria, helping manage storage costs and maintain repository hygiene. The LATEST version is always preserved regardless of age or count.

A version is kept if it meets ANY of these criteria: - Is within the last keep_last_n versions (by creation time) - Is newer than purge_older_than_secs seconds - Is the LATEST version (always preserved)

Parameters:

bsm – AWS session manager for S3 operations
name – Artifact name to clean up
keep_last_n – Minimum number of recent versions to retain
purge_older_than_secs – Maximum age in seconds (default: 90 days)

Returns:

Tuple of (purge_timestamp, list_of_deleted_artifacts)

Examples:

Conservative cleanup (keep 10 versions, 90 days):

purge_time, deleted = repo.purge_artifact_versions(bsm, "myapp")
print(f"Deleted {len(deleted)} old versions")

Aggressive cleanup (keep 3 versions, 7 days):

purge_time, deleted = repo.purge_artifact_versions(
    bsm, "myapp",
    keep_last_n=3,
    purge_older_than_secs=7*24*60*60
)

Dry run analysis:

_, would_delete = repo.purge_artifact_versions(
    bsm, "myapp", keep_last_n=5, purge_older_than_secs=30*24*60*60
)
print(f"Would delete: {[v.version for v in would_delete]}")

Note

This operation cannot be undone. Consider running with restrictive parameters first to verify which versions would be deleted.

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

Completely remove an artifact and all its associated data.

Permanently deletes all versions, aliases, and metadata for the specified artifact. This is equivalent to removing the entire artifact directory from the repository.

Parameters:

bsm – AWS session manager for S3 operations
name – Artifact name to completely remove

Examples:

Remove obsolete artifact:

# Remove an artifact that's no longer maintained
repo.purge_artifact(bsm, "legacy-service")

Clean up test artifacts:

# Remove temporary test artifacts
for test_name in ["test-app-1", "test-app-2"]:
    repo.purge_artifact(bsm, test_name)

Danger

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

purge_all(bsm: BotoSesManager)[source]¶

Completely destroy the entire artifact repository.

Removes all artifacts, versions, aliases, and metadata from the repository. This effectively resets the repository to an empty state while preserving the S3 bucket itself.

Parameters:: bsm – AWS session manager for S3 operations

Examples:

Reset repository for testing:

# Clean slate for integration tests
repo.purge_all(bsm)
repo.bootstrap(bsm)  # Reinitialize

Decommission repository:

# Remove all data before deleting repository
repo.purge_all(bsm)

Danger

This operation is IRREVERSIBLE and will destroy ALL artifacts, versions, and aliases in the repository. Only use for testing or when completely decommissioning the repository.