dxaws-s3

Declarative convergence for Amazon S3 buckets within the dxaws ecosystem.

This module provides a small, stable contract for creating and converging S3 buckets with support for:

• Bucket creation and deletion

• Versioning configuration

• Public access block configuration

• Tag management

• Drift detection and safe re-application

It is intentionally focused and composable — not a general-purpose S3 SDK wrapper.

---

Design Philosophy

dxaws-s3 follows the Declarative Convergence model used across dxaws:

Desired → Current → Plan → Apply → Result

You define the desired state. The module determines the delta and converges AWS resources safely and idempotently.

This keeps infrastructure predictable, testable, and extensible.

---

Quick Example

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

region = "ca-central-1"

provider = AwsS3Provider(region=region)
manager = S3Manager(provider=provider)

desired = S3BucketDesired(
    name="example-bucket",
    region=region,
    tags={"dxaws:env": "dev"},
    versioning=True,
    block_public_access=True,
)

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

Re-applying the same desired state is safe and should result in a no-op.

---

Testing

Unit Tests

make test-unit

Integration Tests

make test-integration

Acceptance Tests (Real AWS)

Acceptance tests create real AWS resources and require valid credentials.

DXAWS_TEST_REGION=ca-central-1 make test-acceptance

Convenience target:

DXAWS_TEST_REGION=ca-central-1 make accept-s3

Optional verbose output:

DXAWS_TEST_REGION=ca-central-1 DXAWS_TEST_DEBUG=1 make accept-s3

---

Documentation

Full documentation is available in the docs/ directory.

To build locally with Sphinx:

python -m pip install "[docs]"
cd docs
make html
open _build/html/index.html

---

Module Status

Version: 0.1.0

This module currently converges bucket existence, versioning, public access block configuration, and tags. Additional features (encryption, lifecycle rules, policy convergence, etc.) may be added in future versions without breaking the public manager/provider contract.