standard-aws 0.2.0__tar.gz

standard_aws-0.2.0/.gitignore

@@ -0,0 +1,31 @@
+# Workspace-managed mounts.
+/.agents/
+/.aws/
+/.codex/
+
+# Python tooling and generated files.
+/.venv/
+/venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+/build/
+/dist/
+/.coverage
+/.coverage.*
+/htmlcov/
+/deprecated/
+/.pytest_cache/
+/.mypy_cache/
+/.ruff_cache/
+/.tox/
+
+# Documentation output.
+/.cache/
+/site/
+
+# Local secrets and environment files.
+.env
+.env.*
+!.env.example
+.kata.local.toml

standard_aws-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Standard contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

standard_aws-0.2.0/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.5
+Name: standard-aws
+Version: 0.2.0
+Summary: Async AWS clients and credential providers for Standard
+Project-URL: Documentation, https://appunni-m.github.io/python-standard/api/
+Project-URL: Repository, https://github.com/appunni-m/python-standard
+Author: Standard contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: aws,boto3,pydantic-settings,standard
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: aioboto3<16,>=13
+Requires-Dist: standard==0.2.0
+Description-Content-Type: text/markdown
+
+# standard-aws
+
+`standard-aws` adds asynchronous AWS clients to the `standard` Python library.
+Install it on its own or select it with the core distribution's extra:
+
+```console
+python -m pip install standard-aws
+python -m pip install 'standard[aws]'
+```
+
+The public import namespace is `std.aws`. The core `standard` package stays
+small; AWS SDK dependencies are installed only with this add-on.
+
+## Credentials
+
+Choose a credential provider explicitly when the application needs a fixed
+source. The default provider delegates to the AWS SDK chain, so environment,
+shared profiles, SSO, web identity, and workload roles keep their SDK behavior.
+
+```python
+from std.aws import DefaultCredentialProvider, ExplicitCredentialProvider
+
+credentials = DefaultCredentialProvider()
+# Or provide short-lived credentials supplied by an application identity system.
+fixed_credentials = ExplicitCredentialProvider(
+    access_key_id="access-key",
+    secret_access_key="secret-key",
+    session_token="session-token",
+    region="us-east-1",
+)
+```
+
+Credential objects hide secret values from their `repr`. Avoid logging values
+returned by `to_dict()` because that method is intended for SDK integration.
+
+## S3
+
+```python
+from std.aws import S3Client, S3ClientConfig
+
+s3 = S3Client(S3ClientConfig(bucket_name="reports", region="us-east-1"))
+await s3.put_object("daily/report.json", '{"ready": true}', content_type="application/json")
+report = await s3.get_object_as_json("daily/report.json")
+keys = await s3.list_objects(prefix="daily/")
+```
+
+`S3Client` also supports file and file-object upload/download, object
+responses, bytes and text reads, Pydantic model validation, copy, deletion,
+presigned GET/PUT/DELETE URLs, and LocalStack or S3-compatible endpoints. S3
+body streams are closed after helper reads. `get_object()` returns the response
+with its body buffered in memory; use `async with s3.open_object(key)` to stream
+large objects while keeping the SDK client open. `list_objects()` accepts
+between 1 and 1000 keys per call, matching S3's service limit.
+
+## SQS
+
+```python
+from std.aws import SQSClient, SQSConfig
+
+queue = SQSClient(SQSConfig(queue_url="https://sqs.us-east-1.amazonaws.com/123/tasks"))
+await queue.send_message({"task_id": "task-123"})
+messages = await queue.receive_message(max_number_of_messages=10, wait_time_seconds=10)
+```
+
+Mappings and Pydantic models are JSON encoded. Batch operations enforce SQS's
+1–10 message limit and reject mismatched per-message attributes. `process_messages`
+supports synchronous and asynchronous handlers; synchronous handlers run outside
+the event loop. Successful messages are deleted only when `auto_delete=True`.
+Failed JSON model parsing leaves the original body intact and adds
+`_parse_error` to the message.
+
+For a continuously polling service, use the lifecycle-aware consumer:
+
+```python
+from std.aws import SQSConsumer
+
+
+async def handle(message):
+    print(message["Body"])
+
+
+consumer = SQSConsumer(queue_url="https://…", region="us-east-1", handler=handle)
+await consumer.start()  # starts its managed worker and returns
+await consumer.stop()  # signals graceful shutdown and waits for completion
+```
+
+`SQSConsumer` is a `std.service.BackgroundService`, so its state and health can
+be managed alongside application services.
+
+## DynamoDB
+
+```python
+from pydantic import BaseModel
+from std.aws import DynamoDBConfig, DynamoTable
+
+
+class Task(BaseModel):
+    task_id: str
+    title: str
+
+
+tasks = DynamoTable(DynamoDBConfig(table_name="tasks"), Task)
+await tasks.put_item(Task(task_id="task-123", title="Build docs"))
+task = await tasks.get_item({"task_id": "task-123"})
+```
+
+The typed helper supports create/delete table, get/put/update/delete item,
+query/scan pagination, and batch read/write. Batch reads and writes are split at
+AWS service limits and retry unprocessed keys or writes a bounded number of
+times. Number attributes deserialize as `Decimal` to preserve precision; sets,
+binary values, nested mappings, lists, booleans, and `None` are supported.
+
+## Secrets Manager settings source
+
+`load_secret()` reads a JSON object from Secrets Manager. Its optional
+`AwsSecretsManagerSettingsSource` adapts that mapping to Pydantic Settings.
+Secret payloads must be JSON objects with unique keys and standard finite JSON
+numbers.
+
+## Testing
+
+Unit tests use fake SDK clients and do not need AWS credentials. The LocalStack
+end-to-end test runs through Testcontainers:
+
+```console
+make test-e2e
+```
+
+The E2E test skips when Docker is unavailable. Set `STD_REQUIRE_DOCKER=1` to
+make a missing Docker daemon a test failure. See the [AWS API guide](../../docs/aws.md)
+for configuration details and edge-case behavior.

standard_aws-0.2.0/README.md

@@ -0,0 +1,131 @@
+# standard-aws
+
+`standard-aws` adds asynchronous AWS clients to the `standard` Python library.
+Install it on its own or select it with the core distribution's extra:
+
+```console
+python -m pip install standard-aws
+python -m pip install 'standard[aws]'
+```
+
+The public import namespace is `std.aws`. The core `standard` package stays
+small; AWS SDK dependencies are installed only with this add-on.
+
+## Credentials
+
+Choose a credential provider explicitly when the application needs a fixed
+source. The default provider delegates to the AWS SDK chain, so environment,
+shared profiles, SSO, web identity, and workload roles keep their SDK behavior.
+
+```python
+from std.aws import DefaultCredentialProvider, ExplicitCredentialProvider
+
+credentials = DefaultCredentialProvider()
+# Or provide short-lived credentials supplied by an application identity system.
+fixed_credentials = ExplicitCredentialProvider(
+    access_key_id="access-key",
+    secret_access_key="secret-key",
+    session_token="session-token",
+    region="us-east-1",
+)
+```
+
+Credential objects hide secret values from their `repr`. Avoid logging values
+returned by `to_dict()` because that method is intended for SDK integration.
+
+## S3
+
+```python
+from std.aws import S3Client, S3ClientConfig
+
+s3 = S3Client(S3ClientConfig(bucket_name="reports", region="us-east-1"))
+await s3.put_object("daily/report.json", '{"ready": true}', content_type="application/json")
+report = await s3.get_object_as_json("daily/report.json")
+keys = await s3.list_objects(prefix="daily/")
+```
+
+`S3Client` also supports file and file-object upload/download, object
+responses, bytes and text reads, Pydantic model validation, copy, deletion,
+presigned GET/PUT/DELETE URLs, and LocalStack or S3-compatible endpoints. S3
+body streams are closed after helper reads. `get_object()` returns the response
+with its body buffered in memory; use `async with s3.open_object(key)` to stream
+large objects while keeping the SDK client open. `list_objects()` accepts
+between 1 and 1000 keys per call, matching S3's service limit.
+
+## SQS
+
+```python
+from std.aws import SQSClient, SQSConfig
+
+queue = SQSClient(SQSConfig(queue_url="https://sqs.us-east-1.amazonaws.com/123/tasks"))
+await queue.send_message({"task_id": "task-123"})
+messages = await queue.receive_message(max_number_of_messages=10, wait_time_seconds=10)
+```
+
+Mappings and Pydantic models are JSON encoded. Batch operations enforce SQS's
+1–10 message limit and reject mismatched per-message attributes. `process_messages`
+supports synchronous and asynchronous handlers; synchronous handlers run outside
+the event loop. Successful messages are deleted only when `auto_delete=True`.
+Failed JSON model parsing leaves the original body intact and adds
+`_parse_error` to the message.
+
+For a continuously polling service, use the lifecycle-aware consumer:
+
+```python
+from std.aws import SQSConsumer
+
+
+async def handle(message):
+    print(message["Body"])
+
+
+consumer = SQSConsumer(queue_url="https://…", region="us-east-1", handler=handle)
+await consumer.start()  # starts its managed worker and returns
+await consumer.stop()  # signals graceful shutdown and waits for completion
+```
+
+`SQSConsumer` is a `std.service.BackgroundService`, so its state and health can
+be managed alongside application services.
+
+## DynamoDB
+
+```python
+from pydantic import BaseModel
+from std.aws import DynamoDBConfig, DynamoTable
+
+
+class Task(BaseModel):
+    task_id: str
+    title: str
+
+
+tasks = DynamoTable(DynamoDBConfig(table_name="tasks"), Task)
+await tasks.put_item(Task(task_id="task-123", title="Build docs"))
+task = await tasks.get_item({"task_id": "task-123"})
+```
+
+The typed helper supports create/delete table, get/put/update/delete item,
+query/scan pagination, and batch read/write. Batch reads and writes are split at
+AWS service limits and retry unprocessed keys or writes a bounded number of
+times. Number attributes deserialize as `Decimal` to preserve precision; sets,
+binary values, nested mappings, lists, booleans, and `None` are supported.
+
+## Secrets Manager settings source
+
+`load_secret()` reads a JSON object from Secrets Manager. Its optional
+`AwsSecretsManagerSettingsSource` adapts that mapping to Pydantic Settings.
+Secret payloads must be JSON objects with unique keys and standard finite JSON
+numbers.
+
+## Testing
+
+Unit tests use fake SDK clients and do not need AWS credentials. The LocalStack
+end-to-end test runs through Testcontainers:
+
+```console
+make test-e2e
+```
+
+The E2E test skips when Docker is unavailable. Set `STD_REQUIRE_DOCKER=1` to
+make a missing Docker daemon a test failure. See the [AWS API guide](../../docs/aws.md)
+for configuration details and edge-case behavior.

standard_aws-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["hatchling>=1.27,<2", "hatch-vcs>=0.4,<1"]
+build-backend = "hatchling.build"
+
+[project]
+name = "standard-aws"
+dynamic = ["version"]
+description = "Async AWS clients and credential providers for Standard"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Standard contributors" }]
+keywords = ["aws", "boto3", "pydantic-settings", "standard"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Typing :: Typed",
+]
+dependencies = ["standard==0.2.0", "aioboto3>=13,<16"]
+urls = { Documentation = "https://appunni-m.github.io/python-standard/api/", Repository = "https://github.com/appunni-m/python-standard" }
+
+[tool.hatch.build.targets.wheel]
+only-include = ["src/std/aws"]
+sources = ["src"]
+
+[tool.hatch.build.targets.sdist]
+only-include = ["pyproject.toml", "README.md", "LICENSE", "src/std/aws"]
+
+[tool.hatch.version]
+source = "vcs"
+tag-pattern = "^v(?P<version>\\d+\\.\\d+\\.\\d+(?:(?:a|b|rc)\\d+)?)$"
+
+[tool.hatch.version.raw-options]
+search_parent_directories = true

standard_aws-0.2.0/src/std/aws/__init__.py

@@ -0,0 +1,134 @@
+"""Asynchronous AWS integrations for Standard applications."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from importlib import import_module
+from typing import Any, NoReturn
+
+from pydantic_settings import BaseSettings, PydanticBaseSettingsSource
+
+from .auth.credentials import (
+    AWSCredentials,
+    CredentialProvider,
+    DefaultCredentialProvider,
+    EnvironmentCredentialProvider,
+    ExplicitCredentialProvider,
+    ProfileCredentialProvider,
+)
+from .dynamodb.table import DynamoDBConfig, DynamoTable
+from .s3.client import S3Client, S3ClientConfig
+from .sqs.client import SQSClient, SQSConfig
+from .sqs.consumer import SQSConsumer
+
+
+class AwsSecretError(RuntimeError):
+    """A secret could not be retrieved or did not contain a JSON object."""
+
+
+def _unique_json_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    """Build a JSON object while rejecting ambiguous duplicate keys."""
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise ValueError("duplicate JSON object key")
+        result[key] = value
+    return result
+
+
+def _reject_non_finite_number(value: str) -> NoReturn:
+    """Reject Python's non-standard JSON NaN and Infinity extensions."""
+    raise ValueError(f"non-standard JSON numeric constant: {value}")
+
+
+def load_secret(
+    secret_id: str,
+    *,
+    region_name: str | None = None,
+    client: Any | None = None,
+) -> dict[str, Any]:
+    """Load a JSON object from AWS Secrets Manager without exposing secret data."""
+    if not secret_id.strip():
+        raise ValueError("secret_id must not be empty")
+    try:
+        if client is None:
+            try:
+                boto3: Any = import_module("boto3")
+            except ImportError as error:  # pragma: no cover - installation dependent
+                raise ImportError(
+                    "AWS Secrets Manager requires boto3; install `standard-aws` or `standard[aws]`."
+                ) from error
+            secrets_client = boto3.client("secretsmanager", region_name=region_name)
+        else:
+            secrets_client = client
+        response = secrets_client.get_secret_value(SecretId=secret_id)
+        if "SecretString" in response:
+            raw = response["SecretString"]
+        elif "SecretBinary" in response:
+            binary = response["SecretBinary"]
+            raw = (
+                binary.decode("utf-8")
+                if isinstance(binary, bytes)
+                else bytes(binary).decode("utf-8")
+            )
+        else:
+            raise AwsSecretError("AWS Secrets Manager returned no secret payload")
+        value = json.loads(
+            raw,
+            object_pairs_hook=_unique_json_object,
+            parse_constant=_reject_non_finite_number,
+        )
+    except (AwsSecretError, ImportError):
+        raise
+    except Exception:
+        raise AwsSecretError("AWS Secrets Manager request or JSON decoding failed") from None
+    if not isinstance(value, Mapping) or any(not isinstance(key, str) for key in value):
+        raise AwsSecretError("AWS secret payload must be a JSON object with string keys")
+    return dict(value)
+
+
+class AwsSecretsManagerSettingsSource(PydanticBaseSettingsSource):
+    """Pydantic source that maps an AWS Secrets Manager JSON object to fields."""
+
+    def __init__(
+        self,
+        settings_cls: type[BaseSettings],
+        secret_id: str,
+        *,
+        region_name: str | None = None,
+        client: Any | None = None,
+    ) -> None:
+        """Configure the source with a Settings model and secret identifier."""
+        super().__init__(settings_cls)
+        self.secret_id = secret_id
+        self.region_name = region_name
+        self.client = client
+
+    def __call__(self) -> dict[str, object]:
+        """Return the secret object as a mapping of Settings field values."""
+        return load_secret(self.secret_id, region_name=self.region_name, client=self.client)
+
+    def get_field_value(self, field: object, field_name: str) -> tuple[object, str, bool]:
+        """Satisfy the Pydantic source protocol; this source returns a full mapping."""
+        return None, field_name, False
+
+
+__all__ = [
+    "AWSCredentials",
+    "AwsSecretError",
+    "AwsSecretsManagerSettingsSource",
+    "CredentialProvider",
+    "DefaultCredentialProvider",
+    "DynamoDBConfig",
+    "DynamoTable",
+    "EnvironmentCredentialProvider",
+    "ExplicitCredentialProvider",
+    "ProfileCredentialProvider",
+    "S3Client",
+    "S3ClientConfig",
+    "SQSClient",
+    "SQSConfig",
+    "SQSConsumer",
+    "load_secret",
+]

standard_aws-0.2.0/src/std/aws/_client.py

@@ -0,0 +1,45 @@
+"""Shared creation of short-lived async AWS SDK clients."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from importlib import import_module
+from typing import Any
+
+from .auth.credentials import CredentialProvider
+
+
+@asynccontextmanager
+async def open_client(
+    service_name: str,
+    *,
+    region: str | None,
+    endpoint_url: str | None,
+    credential_provider: CredentialProvider,
+) -> AsyncIterator[Any]:
+    """Open an aioboto3 client with provider credentials and guaranteed cleanup."""
+    try:
+        aioboto3: Any = import_module("aioboto3")
+    except ImportError as error:  # pragma: no cover - package installation dependent
+        raise ImportError("AWS clients require aioboto3; install `standard-aws`.") from error
+
+    session = aioboto3.Session()
+    kwargs: dict[str, Any] = {}
+    if endpoint_url is not None:
+        kwargs["endpoint_url"] = endpoint_url
+    credentials = await credential_provider.get_credentials()
+    credential_kwargs: dict[str, str] = {}
+    if credentials is not None:
+        credential_kwargs = credentials.to_dict()
+        credential_kwargs.pop("region_name", None)
+    kwargs["region_name"] = (
+        region
+        or (credentials.region if credentials is not None else None)
+        or getattr(session, "region_name", None)
+        or "us-east-1"
+    )
+    kwargs.update(credential_kwargs)
+
+    async with session.client(service_name, **kwargs) as client:
+        yield client

standard_aws-0.2.0/src/std/aws/auth/__init__.py

@@ -0,0 +1,19 @@
+"""Credential providers used by AWS integrations."""
+
+from .credentials import (
+    AWSCredentials,
+    CredentialProvider,
+    DefaultCredentialProvider,
+    EnvironmentCredentialProvider,
+    ExplicitCredentialProvider,
+    ProfileCredentialProvider,
+)
+
+__all__ = [
+    "AWSCredentials",
+    "CredentialProvider",
+    "DefaultCredentialProvider",
+    "EnvironmentCredentialProvider",
+    "ExplicitCredentialProvider",
+    "ProfileCredentialProvider",
+]