Metadata-Version: 2.5
Name: ahi-aws
Version: 0.4.0
Summary: Thin, typed boto3 helpers for AHI: AWS auth (SSO and attached-role sessions), Redshift Data API and Athena query execution, and S3 file storage.
Project-URL: Homepage, https://github.com/adaptivehealthintelligence/ahi-python-packages
Project-URL: Documentation, https://adaptivehealthintelligence.github.io/ahi-python-packages/
Project-URL: Repository, https://github.com/adaptivehealthintelligence/ahi-python-packages
Author: Adaptive Health Intelligence
License: MIT
Keywords: ahi,athena,auth,aws,boto3,redshift,s3,sso,sts
Requires-Python: >=3.11
Requires-Dist: ahi-core<0.3,>=0.2
Requires-Dist: boto3>=1.34
Provides-Extra: types
Requires-Dist: boto3-stubs[athena,redshift-data,s3,sts]>=1.34; extra == 'types'
Description-Content-Type: text/markdown

# ahi-aws

Thin, typed `boto3` helpers for AHI. Today: AWS **auth** (one session, checked
once, with clear errors), running SQL on **Redshift** (Data API) and **Athena**,
with async query handling, and moving files and folders to and from **S3**.

```python
from ahi.aws.auth import aws_session, check_identity

session = aws_session()  # AWS_PROFILE / default profile / attached role
identity = check_identity(session)  # raises an AuthError saying what to run
print(identity.arn, identity.method)  # e.g. "sso", "iam-role", "container-role"
```

```python
from ahi.aws.redshift import RedshiftDataClient
from ahi.aws.athena import AthenaClient

rs = RedshiftDataClient(workgroup_name="analytics", database="dev")
rows = rs.run_query(
    "select count(*) from events where day = :day",
    parameters={"day": "2026-06-26"},
)
print(rows.scalar())

ath = AthenaClient(workgroup="primary", database="analytics")
for row in ath.run_query("select name from users where id = ?", parameters=[42]):
    print(row["name"])
```

```python
from ahi.aws.auth import aws_session
from ahi.aws.s3 import S3Storage

session = aws_session()
storage = S3Storage("s3://my-bucket/some/prefix", client=session.client("s3"))

uploaded = storage.upload_dir("runs/run-01", prefix="run-01")  # list[S3Object]
storage.download_dir("run-01", "local/run-01")
```

## Design notes

- **Never logs in for you.** No browser, no AWS CLI. Run `aws sso login`
  beforehand (local SSO), or run where an AWS role is attached (EC2 instance
  role, ECS task role); missing or expired credentials raise `AuthError`
  with the command to run. No default region: set `AWS_REGION` or the
  profile's `region`.
- **Parameterized queries by default.** Pass values via `parameters` (named
  `:name` for Redshift, positional `?` for Athena) — never format them in.
- **One synchronous call.** `run_query` submits, polls with backoff (see
  `ahi.core.poll_until`), and pages the full result set, returning a
  `QueryResult` you can iterate, `len()`, or call `.scalar()` on.
- **Typed results from Redshift; strings from Athena** (Athena returns all values
  as strings — we preserve that rather than guessing).
- **Failures raise** `QueryFailedError`; timeouts raise `PollTimeoutError`.
- **S3 transfers return `S3Object` records** (bucket, key, local path, size);
  failures raise `UploadFailedError` / `DownloadFailedError`.

Install the optional `types` extra (`ahi-aws[types]`) for `boto3-stubs` during
development.

Part of [ahi-python-packages](https://github.com/adaptivehealthintelligence/ahi-python-packages).
