standard-aws 0.2.0__py3-none-any.whl

standard_aws-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+std/aws/__init__.py,sha256=YUeirBJJS8o0DCrkX1i6oXZCoy38z4YAQjVBUys5csg,4592
+std/aws/_client.py,sha256=TuAsW1Ld7MzWq0xJCLcgdP5gNJocyMt2jGMigPYM3WM,1513
+std/aws/auth/__init__.py,sha256=ne29GcFk7gLN2s9Ot6SfnY2dhP544wnTmtCuyGzZS90,456
+std/aws/auth/credentials.py,sha256=6FjDrx8I52j5lTrMYE9fq7pu6UIZ5qOLjKWYAoKwQfo,6629
+std/aws/dynamodb/__init__.py,sha256=7OpybCCjDQm0jOWBXyrgVuGkD3zYkux2DhyxSI8z8MY,132
+std/aws/dynamodb/table.py,sha256=mIX9041wWZqxkgYoskL9XSyn4wfRroBWdmg-mke61vk,20602
+std/aws/s3/__init__.py,sha256=MIINmPYp_bTZNRXeVBPfZNq404iiQlp1rrUB_89H22w,122
+std/aws/s3/client.py,sha256=_rFWzZpkoyRcin_KVqNqU6YT6omCUPgwFDKWpu6eJao,12310
+std/aws/sqs/__init__.py,sha256=E244DPRphR_0p3PZOwV7B9WyFrAzuYkcsoorBPLna1g,254
+std/aws/sqs/client.py,sha256=UxhA7_uYCMsuBgR_jrIkNTKPCJ-reMOZwokhBMDBhic,11782
+std/aws/sqs/consumer.py,sha256=IstuyoseAc3Yq8iBovtyb2fuK5yz116zAwUMEWUqHus,3980
+standard_aws-0.2.0.dist-info/METADATA,sha256=ia-K1cgRIyOfMgPS66pZSfSl4fnD1kvkYuJl7LsiHZY,5665
+standard_aws-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+standard_aws-0.2.0.dist-info/licenses/LICENSE,sha256=sTIUP5MvMnfCSD0TdNTwjyFwBdAsnTBG2PfgodF7c9k,1078
+standard_aws-0.2.0.dist-info/RECORD,,

standard_aws-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

standard_aws-0.2.0.dist-info/licenses/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.

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",
+]

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

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",
+]

std/aws/auth/credentials.py

@@ -0,0 +1,169 @@
+"""Async credential providers backed by explicit values and the AWS SDK chain."""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from abc import ABC, abstractmethod
+from importlib import import_module
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class AWSCredentials(BaseModel):
+    """AWS access credentials with secret fields hidden from representations."""
+
+    model_config = ConfigDict(extra="forbid", frozen=True, str_strip_whitespace=True)
+
+    access_key_id: str = Field(min_length=1, description="AWS access key ID")
+    secret_access_key: str = Field(min_length=1, repr=False, description="AWS secret access key")
+    session_token: str | None = Field(default=None, repr=False)
+    region: str | None = None
+
+    @field_validator("session_token", "region")
+    @classmethod
+    def _reject_empty_optional_values(cls, value: str | None) -> str | None:
+        if value == "":
+            return None
+        return value
+
+    def to_dict(self) -> dict[str, str]:
+        """Return keyword arguments accepted by the AWS SDK client factory."""
+        values = {
+            "aws_access_key_id": self.access_key_id,
+            "aws_secret_access_key": self.secret_access_key,
+        }
+        if self.session_token is not None:
+            values["aws_session_token"] = self.session_token
+        if self.region is not None:
+            values["region_name"] = self.region
+        return values
+
+
+class CredentialProvider(ABC):
+    """Interface for asynchronous AWS credential lookup."""
+
+    @abstractmethod
+    async def get_credentials(self) -> AWSCredentials | None:
+        """Return credentials, or ``None`` to use the SDK's default chain."""
+
+
+class ExplicitCredentialProvider(CredentialProvider):
+    """Return credentials configured directly by the application."""
+
+    def __init__(
+        self,
+        access_key_id: str,
+        secret_access_key: str,
+        session_token: str | None = None,
+        region: str | None = None,
+    ) -> None:
+        """Validate and retain static credentials for this provider."""
+        self._credentials = AWSCredentials(
+            access_key_id=access_key_id,
+            secret_access_key=secret_access_key,
+            session_token=session_token,
+            region=region,
+        )
+
+    async def get_credentials(self) -> AWSCredentials:
+        """Return the configured credentials."""
+        return self._credentials
+
+
+class EnvironmentCredentialProvider(CredentialProvider):
+    """Read credentials from the standard AWS environment variables."""
+
+    async def get_credentials(self) -> AWSCredentials | None:
+        """Return credentials only when both access-key variables are present."""
+        access_key_id = os.getenv("AWS_ACCESS_KEY_ID")
+        secret_access_key = os.getenv("AWS_SECRET_ACCESS_KEY")
+        if not access_key_id or not secret_access_key:
+            return None
+        return AWSCredentials(
+            access_key_id=access_key_id,
+            secret_access_key=secret_access_key,
+            session_token=os.getenv("AWS_SESSION_TOKEN"),
+            region=os.getenv("AWS_DEFAULT_REGION") or os.getenv("AWS_REGION"),
+        )
+
+
+class ProfileCredentialProvider(CredentialProvider):
+    """Resolve one named profile through the AWS SDK shared configuration chain."""
+
+    def __init__(self, profile_name: str = "default") -> None:
+        """Select the profile name read by the AWS SDK."""
+        if not profile_name.strip():
+            raise ValueError("profile_name must not be empty")
+        self.profile_name = profile_name.strip()
+
+    async def get_credentials(self) -> AWSCredentials | None:
+        """Resolve profile credentials off the event loop, including SSO/process providers."""
+        return await asyncio.to_thread(self._resolve_credentials)
+
+    def _resolve_credentials(self) -> AWSCredentials | None:
+        try:
+            boto3: Any = import_module("boto3")
+        except ImportError as error:  # pragma: no cover - package installation dependent
+            raise ImportError(
+                "AWS credential lookup requires boto3; install `standard-aws`."
+            ) from error
+        try:
+            session = boto3.Session(profile_name=self.profile_name)
+            credentials = session.get_credentials()
+            if credentials is None:
+                return None
+            frozen = credentials.get_frozen_credentials()
+            return AWSCredentials(
+                access_key_id=frozen.access_key,
+                secret_access_key=frozen.secret_key,
+                session_token=frozen.token,
+                region=session.region_name,
+            )
+        except Exception as error:
+            if type(error).__name__ == "ProfileNotFound":
+                return None
+            raise
+
+
+class DefaultCredentialProvider(CredentialProvider):
+    """Resolve the AWS SDK default chain, optionally pinning a named profile."""
+
+    def __init__(self, profile_name: str | None = None) -> None:
+        """Use the normal AWS SDK chain unless a profile name is supplied."""
+        if profile_name is not None and not profile_name.strip():
+            raise ValueError("profile_name must not be empty")
+        self.profile_name = profile_name.strip() if profile_name is not None else None
+
+    async def get_credentials(self) -> AWSCredentials | None:
+        """Return current credentials from the SDK chain without blocking the event loop."""
+        return await asyncio.to_thread(self._resolve_credentials)
+
+    def _resolve_credentials(self) -> AWSCredentials | None:
+        try:
+            boto3: Any = import_module("boto3")
+        except ImportError as error:  # pragma: no cover - package installation dependent
+            raise ImportError(
+                "AWS credential lookup requires boto3; install `standard-aws`."
+            ) from error
+        try:
+            session = (
+                boto3.Session(profile_name=self.profile_name)
+                if self.profile_name is not None
+                else boto3.Session()
+            )
+            credentials = session.get_credentials()
+            if credentials is None:
+                return None
+            frozen = credentials.get_frozen_credentials()
+            return AWSCredentials(
+                access_key_id=frozen.access_key,
+                secret_access_key=frozen.secret_key,
+                session_token=frozen.token,
+                region=session.region_name,
+            )
+        except Exception as error:
+            if type(error).__name__ == "ProfileNotFound":
+                return None
+            raise

std/aws/dynamodb/__init__.py

@@ -0,0 +1,5 @@
+"""Typed DynamoDB table operations."""
+
+from .table import DynamoDBConfig, DynamoTable
+
+__all__ = ["DynamoDBConfig", "DynamoTable"]