capo-ec2 0.5.0__tar.gz

capo_ec2-0.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karen Petrosyan
+
+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.

capo_ec2-0.5.0/PKG-INFO

@@ -0,0 +1,94 @@
+Metadata-Version: 2.4
+Name: capo-ec2
+Version: 0.5.0
+Summary: Python SDK for Amazon EC2.
+Classifier: Development Status :: 4 - Beta
+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.10
+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: Topic :: Software Development :: Code Generators
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jmespath>=1.0
+Requires-Dist: zapros>=0.13.0
+Dynamic: license-file
+
+# Getting Started
+
+## Installation
+
+```
+pip install capo-ec2
+```
+
+## Usage
+
+```python
+from capo_ec2 import AsyncEC2Client
+
+
+async def main():
+    async with AsyncEC2Client() as s3:
+        # Example: call the accept_address_transfer operation
+        response = await s3.accept_address_transfer()
+        print(response["address_transfer"])
+```
+
+## Pagination
+
+Some operations in this SDK support pagination. If the operation supports pagination it will have an `iter_` prefixed method that returns an async iterator.
+
+```python
+from capo_ec2 import AsyncEC2Client
+
+
+async def main():
+    async with AsyncEC2Client() as s3:
+        # Example: paginate over describe_addresses_attribute
+        async for item in s3.iter_describe_addresses_attribute():
+            print(item)
+```
+
+## Waiters
+
+Waiters poll an operation until a resource reaches a desired state. If the operation supports waiters it will have a `wait_until_` prefixed method.
+
+```python
+from capo_ec2 import AsyncEC2Client
+
+
+async def main():
+    async with AsyncEC2Client() as s3:
+        # Example: wait for vpc_peering_connection_exists
+        await s3.wait_until_vpc_peering_connection_exists(max_wait_time=300)
+```
+
+## Retrying
+
+The SDK retries failed operations automatically. Retry behaviour follows the Smithy specification: errors are retried based on their `is_retryable` and `is_throttling_error` attributes. Throttling errors use a longer base delay. Network-level failures (connection errors and timeouts) are also retried. Non-retryable errors, such as client errors without the `@retryable` trait, are raised immediately without further attempts.
+
+The number of attempts defaults to 3 and can be changed at the client level via `retry_max_attempts`, or per call via `config_overrides`.
+
+```python
+from capo_ec2 import AsyncEC2Client
+
+
+async def main():
+    async with AsyncEC2Client() as s3:
+        # Default: 3 attempts for every operation
+        response = await s3.accept_address_transfer()
+
+        # Override per operation
+        response = await s3.accept_address_transfer(config_overrides={"retry_max_attempts": 5})
+
+        # Disable retries for this call
+        response = await s3.accept_address_transfer(config_overrides={"retry_max_attempts": 1})
+```

capo_ec2-0.5.0/README.md

@@ -0,0 +1,71 @@
+# Getting Started
+
+## Installation
+
+```
+pip install capo-ec2
+```
+
+## Usage
+
+```python
+from capo_ec2 import AsyncEC2Client
+
+
+async def main():
+    async with AsyncEC2Client() as s3:
+        # Example: call the accept_address_transfer operation
+        response = await s3.accept_address_transfer()
+        print(response["address_transfer"])
+```
+
+## Pagination
+
+Some operations in this SDK support pagination. If the operation supports pagination it will have an `iter_` prefixed method that returns an async iterator.
+
+```python
+from capo_ec2 import AsyncEC2Client
+
+
+async def main():
+    async with AsyncEC2Client() as s3:
+        # Example: paginate over describe_addresses_attribute
+        async for item in s3.iter_describe_addresses_attribute():
+            print(item)
+```
+
+## Waiters
+
+Waiters poll an operation until a resource reaches a desired state. If the operation supports waiters it will have a `wait_until_` prefixed method.
+
+```python
+from capo_ec2 import AsyncEC2Client
+
+
+async def main():
+    async with AsyncEC2Client() as s3:
+        # Example: wait for vpc_peering_connection_exists
+        await s3.wait_until_vpc_peering_connection_exists(max_wait_time=300)
+```
+
+## Retrying
+
+The SDK retries failed operations automatically. Retry behaviour follows the Smithy specification: errors are retried based on their `is_retryable` and `is_throttling_error` attributes. Throttling errors use a longer base delay. Network-level failures (connection errors and timeouts) are also retried. Non-retryable errors, such as client errors without the `@retryable` trait, are raised immediately without further attempts.
+
+The number of attempts defaults to 3 and can be changed at the client level via `retry_max_attempts`, or per call via `config_overrides`.
+
+```python
+from capo_ec2 import AsyncEC2Client
+
+
+async def main():
+    async with AsyncEC2Client() as s3:
+        # Default: 3 attempts for every operation
+        response = await s3.accept_address_transfer()
+
+        # Override per operation
+        response = await s3.accept_address_transfer(config_overrides={"retry_max_attempts": 5})
+
+        # Disable retries for this call
+        response = await s3.accept_address_transfer(config_overrides={"retry_max_attempts": 1})
+```

capo_ec2-0.5.0/pyproject.toml

@@ -0,0 +1,52 @@
+[project]
+name = "capo-ec2"
+version = "0.5.0"
+description = "Python SDK for Amazon EC2."
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development :: Code Generators",
+    "Typing :: Typed",
+]
+dependencies = [
+    "jmespath>=1.0",
+    "zapros>=0.13.0",
+]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ty.environment]
+python-version = "3.14"
+root = ["./src"]
+
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.ty.rules]
+missing-typed-dict-key = "ignore"
+unused-type-ignore-comment = "ignore"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = ["E501", "E741"]
+
+[dependency-groups]
+dev = [
+    "inline-snapshot>=0.33.0",
+    "ty>=0.0.56",
+    "pytest>=9.0.3",
+    "ruff>=0.15.14",
+    "trio",
+]

capo_ec2-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

capo_ec2-0.5.0/src/capo_ec2/__init__.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+from . import _iter as _iter
+from . import _protocol as _protocol
+from ._auth._identity import Credentials as Credentials
+from ._auth._identity import Identity as Identity
+from ._auth._providers import (
+    CachedProvider as CachedProvider,
+)
+from ._auth._providers import (
+    ChainedProvider as ChainedProvider,
+)
+from ._auth._providers import (
+    CredentialsProvider as CredentialsProvider,
+)
+from ._auth._providers import (
+    EnvCredentialsProvider as EnvCredentialsProvider,
+)
+from ._auth._providers import (
+    IdentityNotFound as IdentityNotFound,
+)
+from ._auth._providers import (
+    IdentityProvider as IdentityProvider,
+)
+from ._auth._providers import (
+    ProfileCredentialsProvider as ProfileCredentialsProvider,
+)
+from ._auth._providers import (
+    StaticAwsCredentialsProvider as StaticAwsCredentialsProvider,
+)
+from ._auth._signers import Signer as Signer
+from ._auth._signers import SigV4Signer as SigV4Signer
+from ._services._pipeline import (
+    AsyncOperationOptions as AsyncOperationOptions,
+)
+from ._services._pipeline import (
+    AsyncOperationRequest as AsyncOperationRequest,
+)
+from ._services._pipeline import (
+    AsyncOperationResponse as AsyncOperationResponse,
+)
+from ._services._pipeline import (
+    OperationOptions as OperationOptions,
+)
+from ._services._pipeline import (
+    OperationRequest as OperationRequest,
+)
+from ._services._pipeline import (
+    OperationResponse as OperationResponse,
+)
+from ._services.async_ec2 import AsyncEC2Client as AsyncEC2Client
+from ._services.ec2 import EC2Client as EC2Client

capo_ec2-0.5.0/src/capo_ec2/_async.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import trio
+else:
+    try:
+        import trio
+    except ImportError:
+        trio = None
+
+
+def in_trio_run() -> bool:
+    if trio is None:
+        return False
+    return trio.lowlevel.in_trio_run()
+
+
+async def anysleep(delay: float) -> None:
+    if in_trio_run():
+        await trio.sleep(delay)
+    else:
+        await asyncio.sleep(delay)

capo_ec2-0.5.0/src/capo_ec2/_auth/_identity.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TypedDict
+
+from typing_extensions import NotRequired
+
+
+class Identity(TypedDict):
+    expiration: NotRequired[datetime | None]
+
+
+class Credentials(Identity):
+    access_key: str
+    secret_key: str
+    session_token: NotRequired[str | None]

capo_ec2-0.5.0/src/capo_ec2/_auth/_providers.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+import configparser
+import os
+from abc import abstractmethod
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Generic, TypeVar
+
+from zapros import AsyncClient, Client, ZaprosError
+
+from capo_ec2._auth._identity import (
+    Credentials,
+    Identity,
+)
+from capo_ec2._services._aws_config import _load_profile
+
+
+class IdentityNotFound(Exception):
+    """Raised when a provider cannot resolve an identity. Chain continues."""
+
+
+IdentityT = TypeVar("IdentityT", bound="Identity")
+
+
+class IdentityProvider(Generic[IdentityT]):
+    @abstractmethod
+    def resolve_identity(self) -> IdentityT:
+        raise NotImplementedError
+
+    async def aresolve_identity(self) -> IdentityT:
+        # default: no network I/O, reuse the sync resolution
+        return self.resolve_identity()
+
+
+class ChainedProvider(IdentityProvider[IdentityT]):
+    """Try each provider in order; first non-`IdentityNotFound` wins."""
+
+    def __init__(self, *providers: IdentityProvider[IdentityT]) -> None:
+        if not providers:
+            raise ValueError("ChainedProvider requires at least one provider")
+        self._providers = providers
+
+    def resolve_identity(self) -> IdentityT:
+        errors: list[str] = []
+        for p in self._providers:
+            try:
+                return p.resolve_identity()
+            except IdentityNotFound as e:
+                errors.append(f"{type(p).__name__}: {e}")
+        raise IdentityNotFound("no provider succeeded: " + "; ".join(errors))
+
+    async def aresolve_identity(self) -> IdentityT:
+        errors: list[str] = []
+        for p in self._providers:
+            try:
+                return await p.aresolve_identity()
+            except IdentityNotFound as e:
+                errors.append(f"{type(p).__name__}: {e}")
+        raise IdentityNotFound("no provider succeeded: " + "; ".join(errors))
+
+
+class CachedProvider(IdentityProvider[IdentityT]):
+    """Cache an identity until its `expiration` (minus skew) elapses."""
+
+    _SKEW_SECONDS = 60
+
+    def __init__(self, inner: IdentityProvider[IdentityT]) -> None:
+        self._inner = inner
+        self._cached: IdentityT | None = None
+
+    def resolve_identity(self) -> IdentityT:
+        if self._cached is not None and not self._expired(self._cached):
+            return self._cached
+        self._cached = self._inner.resolve_identity()
+        return self._cached
+
+    async def aresolve_identity(self) -> IdentityT:
+        if self._cached is not None and not self._expired(self._cached):
+            return self._cached
+        self._cached = await self._inner.aresolve_identity()
+        return self._cached
+
+    @classmethod
+    def _expired(cls, ident: Identity) -> bool:
+        exp = ident.get("expiration")
+        if exp is None:
+            return False
+        return (exp - datetime.now(timezone.utc)).total_seconds() <= cls._SKEW_SECONDS
+
+
+class CredentialsProvider(IdentityProvider[Credentials]):
+    """Base class for providers that resolve AWS `Credentials`."""
+
+    @abstractmethod
+    def resolve_identity(self) -> Credentials:
+        raise NotImplementedError
+
+
+class StaticAwsCredentialsProvider(CredentialsProvider):
+    def __init__(self, credentials: Credentials) -> None:
+        self._credentials = credentials
+
+    def resolve_identity(self) -> Credentials:
+        return self._credentials
+
+
+class EnvCredentialsProvider(CredentialsProvider):
+    """Read AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN."""
+
+    def resolve_identity(self) -> Credentials:
+        ak = os.environ.get("AWS_ACCESS_KEY_ID")
+        sk = os.environ.get("AWS_SECRET_ACCESS_KEY")
+        if not ak or not sk:
+            raise IdentityNotFound("AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY unset")
+        out: Credentials = {"access_key": ak, "secret_key": sk}
+        token = os.environ.get("AWS_SESSION_TOKEN")
+        if token:
+            out["session_token"] = token
+        return out
+
+
+class ProfileCredentialsProvider(CredentialsProvider):
+    """Read ~/.aws/credentials and ~/.aws/config for the active profile."""
+
+    def __init__(self, credentials_file: Path | None = None) -> None:
+        self._profile = (
+            os.environ.get("AWS_PROFILE")
+            or os.environ.get("AWS_DEFAULT_PROFILE")
+            or "default"
+        )
+        self._cred_file = credentials_file or Path(
+            os.environ.get("AWS_SHARED_CREDENTIALS_FILE")
+            or Path.home() / ".aws" / "credentials"
+        )
+
+    def resolve_identity(self) -> Credentials:
+        section = self._load_section()
+        ak = section.get("aws_access_key_id")
+        sk = section.get("aws_secret_access_key")
+        if not ak or not sk:
+            raise IdentityNotFound(
+                f"profile {self._profile!r}: missing aws_access_key_id/aws_secret_access_key"
+            )
+        out: Credentials = {"access_key": ak, "secret_key": sk}
+        token = section.get("aws_session_token")
+        if token:
+            out["session_token"] = token
+        return out
+
+    def _load_section(self) -> dict[str, str]:
+        # config-file profile reuses the loader from _services/_aws_config
+        merged, _ = _load_profile()
+        if self._cred_file.is_file():
+            cfg = configparser.ConfigParser(interpolation=None)
+            cfg.read(self._cred_file)
+            if cfg.has_section(self._profile):
+                merged.update(dict(cfg.items(self._profile)))
+        if not merged:
+            raise IdentityNotFound(
+                f"profile {self._profile!r} not found in credentials/config files"
+            )
+        return merged
+
+
+class EcsContainerCredentialsProvider(CredentialsProvider):
+    """Resolve credentials from the ECS/EKS container credentials endpoint."""
+
+    def __init__(self, client: Client | AsyncClient) -> None:
+        self._client = client
+
+    def resolve_identity(self) -> Credentials:
+        if isinstance(self._client, AsyncClient):
+            raise TypeError(
+                "EcsContainerCredentialsProvider configured with AsyncClient; use aresolve_identity"
+            )
+        url, headers = self._request_args()
+        resp = self._client.get(url, headers=headers)
+        if resp.status < 200 or resp.status >= 300:
+            raise IdentityNotFound(
+                f"ECS credentials endpoint returned status {resp.status}"
+            )
+        return _credentials_from_json(resp.json)
+
+    async def aresolve_identity(self) -> Credentials:
+        if not isinstance(self._client, AsyncClient):
+            raise TypeError(
+                "EcsContainerCredentialsProvider configured with sync Client; use resolve_identity"
+            )
+        url, headers = self._request_args()
+        resp = await self._client.get(url, headers=headers)
+        if resp.status < 200 or resp.status >= 300:
+            raise IdentityNotFound(
+                f"ECS credentials endpoint returned status {resp.status}"
+            )
+        return _credentials_from_json(resp.json)
+
+    def _request_args(self) -> tuple[str, dict[str, str]]:
+        relative = os.environ.get("AWS_CONTAINER_CREDENTIALS_RELATIVE_URI")
+        full = os.environ.get("AWS_CONTAINER_CREDENTIALS_FULL_URI")
+        if relative:
+            url = "http://169.254.170.2" + relative
+        elif full:
+            url = full
+        else:
+            raise IdentityNotFound("no ECS container credentials env var set")
+        headers: dict[str, str] = {}
+        token = os.environ.get("AWS_CONTAINER_AUTHORIZATION_TOKEN")
+        token_file = os.environ.get("AWS_CONTAINER_AUTHORIZATION_TOKEN_FILE")
+        if token_file:
+            token = Path(token_file).read_text().strip()
+        if token:
+            headers["Authorization"] = token
+        return url, headers
+
+
+class Ec2InstanceMetadataProvider(CredentialsProvider):
+    """Resolve credentials from the EC2 Instance Metadata Service (IMDSv2)."""
+
+    _BASE = "http://169.254.169.254"
+    _TOKEN_PATH = "/latest/api/token"
+    _CREDS_PATH = "/latest/meta-data/iam/security-credentials/"
+
+    def __init__(self, client: Client | AsyncClient) -> None:
+        self._client = client
+
+    def resolve_identity(self) -> Credentials:
+        if isinstance(self._client, AsyncClient):
+            raise TypeError(
+                "Ec2InstanceMetadataProvider configured with AsyncClient; use aresolve_identity"
+            )
+        if os.environ.get("AWS_EC2_METADATA_DISABLED", "").strip().lower() in (
+            "true",
+            "1",
+        ):
+            raise IdentityNotFound("IMDS disabled via AWS_EC2_METADATA_DISABLED")
+        try:
+            token_resp = self._client.put(
+                self._BASE + self._TOKEN_PATH,
+                headers={"X-aws-ec2-metadata-token-ttl-seconds": "21600"},
+                body=b"",
+            )
+            auth = {"X-aws-ec2-metadata-token": token_resp.text}
+            role_resp = self._client.get(self._BASE + self._CREDS_PATH, headers=auth)
+            role = role_resp.text.strip()
+            creds_resp = self._client.get(
+                self._BASE + self._CREDS_PATH + role, headers=auth
+            )
+        except ZaprosError as e:
+            raise IdentityNotFound(f"IMDS request failed: {e}")
+        if creds_resp.status < 200 or creds_resp.status >= 300:
+            raise IdentityNotFound(f"IMDS returned status {creds_resp.status}")
+        return _credentials_from_json(creds_resp.json)
+
+    async def aresolve_identity(self) -> Credentials:
+        if not isinstance(self._client, AsyncClient):
+            raise TypeError(
+                "Ec2InstanceMetadataProvider configured with sync Client; use resolve_identity"
+            )
+        if os.environ.get("AWS_EC2_METADATA_DISABLED", "").strip().lower() in (
+            "true",
+            "1",
+        ):
+            raise IdentityNotFound("IMDS disabled via AWS_EC2_METADATA_DISABLED")
+        try:
+            token_resp = await self._client.put(
+                self._BASE + self._TOKEN_PATH,
+                headers={"X-aws-ec2-metadata-token-ttl-seconds": "21600"},
+                body=b"",
+            )
+            auth = {"X-aws-ec2-metadata-token": token_resp.text}
+            role_resp = await self._client.get(
+                self._BASE + self._CREDS_PATH, headers=auth
+            )
+            role = role_resp.text.strip()
+            creds_resp = await self._client.get(
+                self._BASE + self._CREDS_PATH + role, headers=auth
+            )
+        except ZaprosError as e:
+            raise IdentityNotFound(f"IMDS request failed: {e}")
+        if creds_resp.status < 200 or creds_resp.status >= 300:
+            raise IdentityNotFound(f"IMDS returned status {creds_resp.status}")
+        return _credentials_from_json(creds_resp.json)
+
+
+def _parse_iso8601(value: str) -> datetime:
+    # tolerate trailing 'Z'
+    return datetime.fromisoformat(value.replace("Z", "+00:00"))
+
+
+def _credentials_from_json(data: dict[str, object]) -> Credentials:
+    ak = data.get("AccessKeyId")
+    sk = data.get("SecretAccessKey")
+    if not isinstance(ak, str) or not isinstance(sk, str):
+        raise IdentityNotFound(
+            "credentials response missing AccessKeyId/SecretAccessKey"
+        )
+    out: Credentials = {"access_key": ak, "secret_key": sk}
+    token = data.get("Token")
+    if isinstance(token, str):
+        out["session_token"] = token
+    exp = data.get("Expiration")
+    if isinstance(exp, str):
+        out["expiration"] = _parse_iso8601(exp)
+    return out
+
+
+def default_aws_credentials_chain(
+    client: Client | AsyncClient,
+) -> IdentityProvider[Credentials]:
+    return CachedProvider(
+        ChainedProvider(
+            EnvCredentialsProvider(),
+            ProfileCredentialsProvider(),
+            EcsContainerCredentialsProvider(client),
+            Ec2InstanceMetadataProvider(client),
+        )
+    )