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).