# 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:

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

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

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

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

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

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