# 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

```python
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

```bash
make test-unit
```

### Integration Tests

```bash
make test-integration
```

### Acceptance Tests (Real AWS)

Acceptance tests create real AWS resources and require valid credentials.

```bash
DXAWS_TEST_REGION=ca-central-1 make test-acceptance
```

Convenience target:

```bash
DXAWS_TEST_REGION=ca-central-1 make accept-s3
```

Optional verbose output:

```bash
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:

```bash
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.