samstack 0.1.0__py3-none-any.whl

samstack/resources/dynamodb.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from mypy_boto3_dynamodb import DynamoDBClient
+    from mypy_boto3_dynamodb.service_resource import Table
+
+
+class DynamoTable:
+    """
+    Thin wrapper around a DynamoDB table resource for use in pytest fixtures.
+
+    Uses the high-level boto3 resource API so item values are plain Python
+    types (str, int, list, dict) — not the low-level ``{"S": "val"}`` format.
+
+    The underlying boto3 resource is exposed via the ``table`` property, and
+    the low-level DynamoDB client is available via the ``client`` property.
+    """
+
+    def __init__(self, name: str, table: Table) -> None:
+        self._name = name
+        self._table = table
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def table(self) -> Table:
+        """The underlying boto3 DynamoDB Table resource."""
+        return self._table
+
+    @property
+    def client(self) -> DynamoDBClient:
+        """The underlying low-level DynamoDB client for advanced operations."""
+        client: DynamoDBClient = self._table.meta.client
+        return client
+
+    def put_item(self, item: dict[str, Any]) -> None:
+        """Write an item to the table using plain Python values."""
+        self._table.put_item(Item=item)
+
+    def get_item(self, key: dict[str, Any]) -> dict[str, Any] | None:
+        """Fetch an item by key. Returns None if the item does not exist."""
+        resp = self._table.get_item(Key=key)
+        return resp.get("Item")
+
+    def delete_item(self, key: dict[str, Any]) -> None:
+        """Delete an item by key."""
+        self._table.delete_item(Key=key)
+
+    def query(
+        self,
+        key_condition: str,
+        values: dict[str, Any],
+        **kwargs: Any,
+    ) -> list[dict[str, Any]]:
+        """
+        Query items by key condition expression.
+
+        Args:
+            key_condition: KeyConditionExpression string, e.g. ``"pk = :pk"``
+            values: ExpressionAttributeValues dict, e.g. ``{":pk": "val"}``
+            **kwargs: Extra args forwarded to boto3 (e.g. ``IndexName``)
+        """
+        resp = self._table.query(
+            KeyConditionExpression=key_condition,
+            ExpressionAttributeValues=values,
+            **kwargs,
+        )
+        return resp["Items"]
+
+    def scan(self, **kwargs: Any) -> list[dict[str, Any]]:
+        """Scan all items, with optional filter kwargs forwarded to boto3."""
+        resp = self._table.scan(**kwargs)
+        return resp["Items"]

samstack/resources/s3.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from mypy_boto3_s3 import S3Client
+
+
+class S3Bucket:
+    """Thin wrapper around an S3 bucket for use in pytest fixtures."""
+
+    def __init__(self, name: str, client: S3Client) -> None:
+        self._name = name
+        self._client = client
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def client(self) -> S3Client:
+        return self._client
+
+    def put(self, key: str, data: bytes | str | dict[str, Any]) -> None:
+        """Upload an object. Dicts are JSON-serialized; strings are UTF-8 encoded."""
+        if isinstance(data, dict):
+            body: bytes = json.dumps(data).encode()
+        elif isinstance(data, str):
+            body = data.encode()
+        else:
+            body = data
+        self._client.put_object(Bucket=self._name, Key=key, Body=body)
+
+    def get(self, key: str) -> bytes:
+        """Download an object and return raw bytes."""
+        resp = self._client.get_object(Bucket=self._name, Key=key)
+        return resp["Body"].read()
+
+    def get_json(self, key: str) -> Any:
+        """Download an object and deserialize as JSON."""
+        return json.loads(self.get(key))
+
+    def delete(self, key: str) -> None:
+        """Delete an object."""
+        self._client.delete_object(Bucket=self._name, Key=key)
+
+    def list_keys(self, prefix: str = "") -> list[str]:
+        """List object keys, optionally filtered by prefix."""
+        resp = self._client.list_objects_v2(Bucket=self._name, Prefix=prefix)
+        return [obj["Key"] for obj in resp.get("Contents", [])]

samstack/resources/sns.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from mypy_boto3_sns import SNSClient
+
+
+class SnsTopic:
+    """Thin wrapper around an SNS topic for use in pytest fixtures."""
+
+    def __init__(self, arn: str, client: SNSClient) -> None:
+        self._arn = arn
+        self._client = client
+
+    @property
+    def arn(self) -> str:
+        return self._arn
+
+    @property
+    def client(self) -> SNSClient:
+        return self._client
+
+    def publish(
+        self,
+        message: str | dict[str, Any],
+        subject: str | None = None,
+    ) -> str:
+        """
+        Publish a message to the topic. Dicts are JSON-serialized.
+        Returns the message ID.
+        """
+        body = json.dumps(message) if isinstance(message, dict) else message
+        kwargs: dict[str, Any] = {"TopicArn": self._arn, "Message": body}
+        if subject is not None:
+            kwargs["Subject"] = subject
+        resp = self._client.publish(**kwargs)
+        return resp["MessageId"]
+
+    def subscribe_sqs(self, queue_arn: str) -> str:
+        """
+        Subscribe an SQS queue to this topic.
+
+        Args:
+            queue_arn: The ARN of the SQS queue to receive messages.
+
+        Returns:
+            The subscription ARN.
+        """
+        resp = self._client.subscribe(
+            TopicArn=self._arn,
+            Protocol="sqs",
+            Endpoint=queue_arn,
+        )
+        return resp["SubscriptionArn"]

samstack/resources/sqs.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from mypy_boto3_sqs import SQSClient
+    from mypy_boto3_sqs.type_defs import MessageTypeDef
+
+
+class SqsQueue:
+    """Thin wrapper around an SQS queue for use in pytest fixtures."""
+
+    def __init__(self, url: str, client: SQSClient) -> None:
+        self._url = url
+        self._client = client
+
+    @property
+    def url(self) -> str:
+        return self._url
+
+    @property
+    def client(self) -> SQSClient:
+        return self._client
+
+    def send(self, body: str | dict[str, Any], **kwargs: Any) -> str:
+        """
+        Send a message. Dicts are JSON-serialized. Returns the message ID.
+        Extra kwargs (e.g. ``DelaySeconds``) are forwarded to boto3.
+        """
+        message_body = json.dumps(body) if isinstance(body, dict) else body
+        resp = self._client.send_message(
+            QueueUrl=self._url, MessageBody=message_body, **kwargs
+        )
+        return resp["MessageId"]
+
+    def receive(
+        self, max_messages: int = 1, wait_seconds: int = 0
+    ) -> list[MessageTypeDef]:
+        """
+        Receive messages from the queue.
+
+        Returns a list of message dicts (``MessageId``, ``Body``,
+        ``ReceiptHandle``, etc). Returns an empty list when the queue is empty.
+        """
+        resp = self._client.receive_message(
+            QueueUrl=self._url,
+            MaxNumberOfMessages=max_messages,
+            WaitTimeSeconds=wait_seconds,
+        )
+        return resp.get("Messages", [])
+
+    def purge(self) -> None:
+        """Delete all messages from the queue."""
+        self._client.purge_queue(QueueUrl=self._url)

samstack/settings.py

@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+import dataclasses
+import platform
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+
+def _detect_architecture() -> Literal["arm64", "x86_64"]:
+    """Return 'arm64' on Apple Silicon / Linux ARM hosts, 'x86_64' otherwise.
+
+    platform.machine() returns:
+      - 'arm64'   on macOS ARM (Apple Silicon)
+      - 'aarch64' on Linux ARM64
+      - 'x86_64'  on Intel/AMD (macOS and Linux)
+    """
+    machine = platform.machine().lower()
+    if machine in ("arm64", "aarch64"):
+        return "arm64"
+    return "x86_64"
+
+
+@dataclass(frozen=True)
+class SamStackSettings:
+    sam_image: str
+    template: str = "template.yaml"
+    region: str = "us-east-1"
+    api_port: int = 3000
+    lambda_port: int = 3001
+    localstack_image: str = "localstack/localstack:4"
+    log_dir: str = "logs/sam"
+    build_args: list[str] = field(default_factory=list)
+    add_gitignore: bool = True
+    start_api_args: list[str] = field(default_factory=list)
+    start_lambda_args: list[str] = field(default_factory=list)
+    project_root: Path = field(default_factory=Path.cwd)
+    architecture: Literal["arm64", "x86_64"] = field(
+        default_factory=_detect_architecture
+    )
+
+    @property
+    def docker_platform(self) -> str:
+        return "linux/arm64" if self.architecture == "arm64" else "linux/amd64"
+
+
+def load_settings(project_root: Path) -> SamStackSettings:
+    """Parse [tool.samstack] from pyproject.toml in project_root."""
+    pyproject = project_root / "pyproject.toml"
+    with pyproject.open("rb") as f:
+        data = tomllib.load(f)
+
+    tool = data.get("tool", {})
+    if "samstack" not in tool:
+        raise ValueError(
+            "[tool.samstack] section not found in pyproject.toml. "
+            "Add it to configure samstack."
+        )
+
+    cfg: dict = tool["samstack"]
+
+    if not cfg.get("sam_image"):
+        raise ValueError(
+            "sam_image is required in [tool.samstack]. "
+            'Example: sam_image = "public.ecr.aws/sam/build-python3.13"'
+        )
+
+    arch = cfg.get("architecture")
+    if arch is not None and arch not in ("arm64", "x86_64"):
+        raise ValueError(
+            f"architecture must be 'arm64' or 'x86_64', got '{arch}'. "
+            "Remove the field to auto-detect from the host machine."
+        )
+
+    # Let the dataclass field defaults be the single source of truth.
+    # TOML already parses integers natively; list/bool/str fields pass through unchanged.
+    known = {f.name for f in dataclasses.fields(SamStackSettings)} - {
+        "sam_image",
+        "project_root",
+    }
+    filtered = {k: v for k, v in cfg.items() if k in known}
+    return SamStackSettings(
+        sam_image=cfg["sam_image"], project_root=project_root, **filtered
+    )