# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

```bash
make lint              # ruff check + format check
make format            # auto-fix with ruff (check + format)
make run_unit_tests    # pytest tests/
make lint_and_test     # lint then test

# Run a single test file
pytest tests/test_s3_handler.py

# Run a single test
pytest tests/test_s3_handler.py::TestS3Handler::test_put
```

CI runs `make docker_run_lint_and_test` (builds Docker image, runs lint + tests inside).

## Code Style

Ruff is the only linter/formatter. Key settings:
- Line length: 88
- Single quotes (strings and inline)
- Import sorting (isort-compatible, rule set I)

## Architecture

This is a boto3 abstraction library for AWS integration testing. It provides assertion-friendly wrappers around AWS service clients, intended for use in test suites rather than production code.

**Package**: `aws_testing_utils/`

Each AWS service has a dedicated handler class:

| Handler | Service | Key methods |
|---|---|---|
| `LambdaHandler` | Lambda | `invoke()` with StatusCode/FunctionError assertions |
| `S3Handler` | S3 | `put()`, `get_s3_object_data()`, `verify_s3_object_sha256()`, existence checks |
| `SQSHandler` | SQS | `read_message()` (receive+delete), `purge()` (with auto-retry) |
| `DynamoDBHandler` | DynamoDB | `get()`, `put()`, `table()` |
| `StepFunctionHandler` | Step Functions | `execute()`, `assert_execution_success()`, polling logic |
| `CloudwatchLogHandler` | CloudWatch Logs | `assert_lambda_invoked()`, `assert_lambda_logs_message()` |

`config.py` reads `AWS_DEFAULT_REGION` (default `us-east-1`) and `ENV` (default `qa`) from env vars. `LAMBDA_ENDPOINT_URL` is also read; when set, `LambdaHandler` will target that endpoint instead of real AWS (empty string is treated as unset).

`logger.py` is a singleton file logger writing to `automation.log`, auto-detecting caller name from the call stack.

**Design pattern**: Methods frequently accept `assertion` parameters or raise exceptions for failed assertions directly. CloudWatch and Step Function handlers include polling loops (`max_tries`, `seconds_to_wait`). All boto3 calls are wrapped — tests mock at the boto3 level using `unittest.mock`.

## Versioning and Publishing

**Do not manually edit the version in `aws_testing_utils/__init__.py` or `.bumpversion.cfg`.** Version bumps and publishing are fully automated via the Jenkins pipeline at `https://pipeline.theorchard.io/job/publish-pypi-package-v2/` — run it once for an RC, then again with the release option to promote. The pipeline handles all version file updates.