↓ Skip to main content
dxaws

dxaws-s3 / usage

·349 words·2 mins
Table of Contents

Usage
#

This module is Python-first. Higher-level orchestration (CLI/runbooks) can call the manager, but the stable contract lives in the S3Manager + provider interface.

Basic Example
#

Create (or converge) an S3 bucket to a desired spec:

from dxaws_s3.manager import S3Manager
from dxaws_s3.models import S3BucketDesired

region = "ca-central-1"

# AWS is the default provider.
manager = S3Manager()

# Region is part of desired state so the manager can route AWS calls correctly.
desired = S3BucketDesired(
    name="example-bucket-name",
    region=region,
    tags={
        "dxaws:module": "dxaws-s3",
        "dxaws:env": "dev",
    },
    versioning=True,
    block_public_access=True,
)

result = manager.apply(desired)
print(result)

Idempotency
#

Re-applying the same desired state should be safe:

manager.apply(desired)
manager.apply(desired)  # should be a no-op (or minimal API calls)

Drift and Convergence
#

If someone changes bucket configuration out-of-band, re-applying the same desired state should converge it back:

# someone disables public access block out-of-band...

manager.apply(desired)  # converges versioning / PAB / tags back to desired

Planning
#

If you want to preview changes before applying them, use plan:

plan = manager.plan(desired)
for action in plan.actions:
    print(action.type, action.details)

(Exact action types may evolve, but the manager/desired contract is intended to remain stable and extendable.)

Overriding the Provider
#

Most callers should use S3Manager() directly and treat providers as an internal implementation detail.

Providers exist for dependency injection (unit/integration tests, recording providers, alternate backends). If you need to override the provider explicitly, you can:

from dxaws_s3.manager import S3Manager
from dxaws_s3.models import S3BucketDesired
from dxaws_s3.providers.aws import AwsS3Provider

region = "ca-central-1"
manager = S3Manager(provider=AwsS3Provider(region=region))

desired = S3BucketDesired(
    name="example-bucket-name",
    region=region,
    tags={"dxaws:module": "dxaws-s3", "dxaws:env": "dev"},
)

manager.apply(desired)

If your provider needs extra configuration (profiles, custom sessions, etc.), prefer adding that to the manager surface or desired models rather than having higher-level orchestration call provider methods directly.

Acceptance Tests
#

Acceptance tests create real AWS resources.

Use the Makefile targets:

# Unit tests
make test-unit

# Integration tests
make test-integration

# Full acceptance suite (real AWS)
DXAWS_TEST_REGION=ca-central-1 make test-acceptance

# S3-only acceptance run
DXAWS_TEST_REGION=ca-central-1 make accept-s3

# Optional: more verbose acceptance output
DXAWS_TEST_REGION=ca-central-1 DXAWS_TEST_DEBUG=1 make accept-s3

Acceptance tests also require valid AWS credentials in your environment (SSO, profiles, or other supported credential chains).