samstack 0.1.0__py3-none-any.whl

samstack/fixtures/resources.py

@@ -0,0 +1,376 @@
+"""
+LocalStack resource fixtures for testing AWS services.
+
+Provides session-scoped boto3 clients, session-scoped factory fixtures,
+and function-scoped convenience fixtures for S3, DynamoDB, SQS, and SNS.
+"""
+
+from __future__ import annotations
+
+import warnings
+from collections.abc import Callable, Iterator
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+from uuid import uuid4
+
+import boto3
+import pytest
+
+from samstack._constants import LOCALSTACK_ACCESS_KEY, LOCALSTACK_SECRET_KEY
+from samstack.resources.dynamodb import DynamoTable
+from samstack.resources.s3 import S3Bucket
+from samstack.resources.sns import SnsTopic
+from samstack.resources.sqs import SqsQueue
+from samstack.settings import SamStackSettings
+
+
+@contextmanager
+def _safe_cleanup(description: str) -> Iterator[None]:
+    try:
+        yield
+    except Exception as exc:
+        warnings.warn(
+            f"samstack: failed to clean up {description}: {exc}",
+            stacklevel=1,
+        )
+
+
+if TYPE_CHECKING:
+    from mypy_boto3_dynamodb import DynamoDBClient
+    from mypy_boto3_dynamodb.service_resource import DynamoDBServiceResource, Table
+    from mypy_boto3_s3 import S3Client
+    from mypy_boto3_sns import SNSClient
+    from mypy_boto3_sqs import SQSClient
+
+
+# ---------------------------------------------------------------------------
+# S3
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(scope="session")
+def s3_client(
+    localstack_endpoint: str,
+    samstack_settings: SamStackSettings,
+) -> S3Client:
+    """Session-scoped boto3 S3 client pointed at LocalStack."""
+    return boto3.client(
+        "s3",
+        endpoint_url=localstack_endpoint,
+        region_name=samstack_settings.region,
+        aws_access_key_id=LOCALSTACK_ACCESS_KEY,
+        aws_secret_access_key=LOCALSTACK_SECRET_KEY,
+    )
+
+
+@pytest.fixture(scope="session")
+def s3_bucket_factory(
+    s3_client: S3Client,
+) -> Iterator[Callable[[str], S3Bucket]]:
+    """
+    Session-scoped factory that creates S3Bucket instances.
+
+    Each call creates a uniquely named bucket. All buckets are deleted
+    at end of session.
+
+    Usage::
+
+        def test_something(s3_bucket_factory):
+            bucket = s3_bucket_factory("my-data")
+            bucket.put("key.json", {"value": 1})
+    """
+    created: list[S3Bucket] = []
+
+    def _create(name: str) -> S3Bucket:
+        actual = f"{name}-{uuid4().hex[:8]}"
+        s3_client.create_bucket(Bucket=actual)
+        bucket = S3Bucket(name=actual, client=s3_client)
+        created.append(bucket)
+        return bucket
+
+    yield _create
+
+    for bucket in created:
+        with _safe_cleanup(f"S3 bucket '{bucket.name}'"):
+            for key in bucket.list_keys():
+                bucket.delete(key)
+            s3_client.delete_bucket(Bucket=bucket.name)
+
+
+@pytest.fixture
+def s3_bucket(s3_client: S3Client) -> Iterator[S3Bucket]:
+    """
+    Function-scoped S3Bucket fixture. Fresh bucket per test, deleted after.
+
+    Usage::
+
+        def test_upload(s3_bucket):
+            s3_bucket.put("file.txt", b"hello")
+            assert s3_bucket.get("file.txt") == b"hello"
+    """
+    name = f"test-{uuid4().hex[:8]}"
+    s3_client.create_bucket(Bucket=name)
+    bucket = S3Bucket(name=name, client=s3_client)
+    yield bucket
+    with _safe_cleanup(f"S3 bucket '{name}'"):
+        for key in bucket.list_keys():
+            bucket.delete(key)
+        s3_client.delete_bucket(Bucket=name)
+
+
+# ---------------------------------------------------------------------------
+# DynamoDB
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(scope="session")
+def dynamodb_client(
+    localstack_endpoint: str,
+    samstack_settings: SamStackSettings,
+) -> DynamoDBClient:
+    """Session-scoped boto3 DynamoDB low-level client pointed at LocalStack."""
+    return boto3.client(
+        "dynamodb",
+        endpoint_url=localstack_endpoint,
+        region_name=samstack_settings.region,
+        aws_access_key_id=LOCALSTACK_ACCESS_KEY,
+        aws_secret_access_key=LOCALSTACK_SECRET_KEY,
+    )
+
+
+@pytest.fixture(scope="session")
+def _dynamodb_resource(
+    localstack_endpoint: str,
+    samstack_settings: SamStackSettings,
+) -> DynamoDBServiceResource:
+    """Session-scoped boto3 DynamoDB resource (high-level) for table wrappers."""
+    return boto3.resource(
+        "dynamodb",
+        endpoint_url=localstack_endpoint,
+        region_name=samstack_settings.region,
+        aws_access_key_id=LOCALSTACK_ACCESS_KEY,
+        aws_secret_access_key=LOCALSTACK_SECRET_KEY,
+    )
+
+
+def _create_dynamo_table(
+    dynamodb_client: DynamoDBClient,
+    resource: DynamoDBServiceResource,
+    name: str,
+    keys: dict[str, str],
+) -> DynamoTable:
+    key_pairs = list(keys.items())
+    attr_defs = [{"AttributeName": k, "AttributeType": v} for k, v in key_pairs]
+    key_schema = [{"AttributeName": key_pairs[0][0], "KeyType": "HASH"}]
+    if len(key_pairs) > 1:
+        key_schema.append({"AttributeName": key_pairs[1][0], "KeyType": "RANGE"})
+    dynamodb_client.create_table(
+        TableName=name,
+        AttributeDefinitions=attr_defs,
+        KeySchema=key_schema,
+        BillingMode="PAY_PER_REQUEST",
+    )
+    table: Table = resource.Table(name)
+    return DynamoTable(name=name, table=table)
+
+
+@pytest.fixture(scope="session")
+def dynamodb_table_factory(
+    dynamodb_client: DynamoDBClient,
+    _dynamodb_resource: DynamoDBServiceResource,
+) -> Iterator[Callable[[str, dict[str, str]], DynamoTable]]:
+    """
+    Session-scoped factory that creates DynamoTable instances.
+
+    Each call creates a uniquely named table. All tables are deleted at end of session.
+    Uses the high-level resource API so item values are plain Python types.
+
+    Args:
+        name: Base name for the table (UUID suffix appended).
+        keys: Mapping of attribute name to type (``"S"``, ``"N"``, or ``"B"``).
+              First entry is the HASH key; second (if present) is the RANGE key.
+
+    Usage::
+
+        def test_something(dynamodb_table_factory):
+            table = dynamodb_table_factory("orders", {"order_id": "S"})
+            table.put_item({"order_id": "1", "total": 99})
+    """
+    created: list[str] = []
+
+    def _create(name: str, keys: dict[str, str]) -> DynamoTable:
+        actual = f"{name}-{uuid4().hex[:8]}"
+        table = _create_dynamo_table(dynamodb_client, _dynamodb_resource, actual, keys)
+        created.append(actual)
+        return table
+
+    yield _create
+
+    for table_name in created:
+        with _safe_cleanup(f"DynamoDB table '{table_name}'"):
+            dynamodb_client.delete_table(TableName=table_name)
+
+
+@pytest.fixture
+def dynamodb_table(
+    dynamodb_client: DynamoDBClient,
+    _dynamodb_resource: DynamoDBServiceResource,
+) -> Iterator[DynamoTable]:
+    """
+    Function-scoped DynamoTable fixture. Default key schema: ``{"id": "S"}``.
+    Fresh table per test, deleted after.
+
+    Usage::
+
+        def test_store(dynamodb_table):
+            dynamodb_table.put_item({"id": "1", "data": "x"})
+            assert dynamodb_table.get_item({"id": "1"})["data"] == "x"
+    """
+    name = f"test-{uuid4().hex[:8]}"
+    table = _create_dynamo_table(dynamodb_client, _dynamodb_resource, name, {"id": "S"})
+    yield table
+    with _safe_cleanup(f"DynamoDB table '{name}'"):
+        dynamodb_client.delete_table(TableName=name)
+
+
+# ---------------------------------------------------------------------------
+# SQS
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(scope="session")
+def sqs_client(
+    localstack_endpoint: str,
+    samstack_settings: SamStackSettings,
+) -> SQSClient:
+    """Session-scoped boto3 SQS client pointed at LocalStack."""
+    return boto3.client(
+        "sqs",
+        endpoint_url=localstack_endpoint,
+        region_name=samstack_settings.region,
+        aws_access_key_id=LOCALSTACK_ACCESS_KEY,
+        aws_secret_access_key=LOCALSTACK_SECRET_KEY,
+    )
+
+
+@pytest.fixture(scope="session")
+def sqs_queue_factory(
+    sqs_client: SQSClient,
+) -> Iterator[Callable[[str], SqsQueue]]:
+    """
+    Session-scoped factory that creates SqsQueue instances.
+
+    Each call creates a uniquely named queue. All queues are deleted at end of session.
+
+    Usage::
+
+        def test_something(sqs_queue_factory):
+            queue = sqs_queue_factory("jobs")
+            queue.send({"task": "process", "id": 1})
+    """
+    created: list[SqsQueue] = []
+
+    def _create(name: str) -> SqsQueue:
+        actual = f"{name}-{uuid4().hex[:8]}"
+        resp = sqs_client.create_queue(QueueName=actual)
+        queue = SqsQueue(url=resp["QueueUrl"], client=sqs_client)
+        created.append(queue)
+        return queue
+
+    yield _create
+
+    for queue in created:
+        with _safe_cleanup(f"SQS queue '{queue.url}'"):
+            sqs_client.delete_queue(QueueUrl=queue.url)
+
+
+@pytest.fixture
+def sqs_queue(sqs_client: SQSClient) -> Iterator[SqsQueue]:
+    """
+    Function-scoped SqsQueue fixture. Fresh queue per test, deleted after.
+
+    Usage::
+
+        def test_process(sqs_queue):
+            sqs_queue.send({"job": "run"})
+            messages = sqs_queue.receive()
+            assert len(messages) == 1
+    """
+    name = f"test-{uuid4().hex[:8]}"
+    resp = sqs_client.create_queue(QueueName=name)
+    queue = SqsQueue(url=resp["QueueUrl"], client=sqs_client)
+    yield queue
+    with _safe_cleanup(f"SQS queue '{name}'"):
+        sqs_client.delete_queue(QueueUrl=queue.url)
+
+
+# ---------------------------------------------------------------------------
+# SNS
+# ---------------------------------------------------------------------------
+
+
+@pytest.fixture(scope="session")
+def sns_client(
+    localstack_endpoint: str,
+    samstack_settings: SamStackSettings,
+) -> SNSClient:
+    """Session-scoped boto3 SNS client pointed at LocalStack."""
+    return boto3.client(
+        "sns",
+        endpoint_url=localstack_endpoint,
+        region_name=samstack_settings.region,
+        aws_access_key_id=LOCALSTACK_ACCESS_KEY,
+        aws_secret_access_key=LOCALSTACK_SECRET_KEY,
+    )
+
+
+@pytest.fixture(scope="session")
+def sns_topic_factory(
+    sns_client: SNSClient,
+) -> Iterator[Callable[[str], SnsTopic]]:
+    """
+    Session-scoped factory that creates SnsTopic instances.
+
+    Each call creates a uniquely named topic. All topics are deleted at end of session.
+
+    Usage::
+
+        def test_something(sns_topic_factory, sqs_queue_factory):
+            topic = sns_topic_factory("notifications")
+            queue = sqs_queue_factory("inbox")
+            topic.subscribe_sqs(queue_arn)
+            topic.publish({"event": "created"})
+    """
+    created: list[SnsTopic] = []
+
+    def _create(name: str) -> SnsTopic:
+        actual = f"{name}-{uuid4().hex[:8]}"
+        resp = sns_client.create_topic(Name=actual)
+        topic = SnsTopic(arn=resp["TopicArn"], client=sns_client)
+        created.append(topic)
+        return topic
+
+    yield _create
+
+    for topic in created:
+        with _safe_cleanup(f"SNS topic '{topic.arn}'"):
+            sns_client.delete_topic(TopicArn=topic.arn)
+
+
+@pytest.fixture
+def sns_topic(sns_client: SNSClient) -> Iterator[SnsTopic]:
+    """
+    Function-scoped SnsTopic fixture. Fresh topic per test, deleted after.
+
+    Usage::
+
+        def test_notify(sns_topic):
+            msg_id = sns_topic.publish("hello")
+            assert isinstance(msg_id, str)
+    """
+    name = f"test-{uuid4().hex[:8]}"
+    resp = sns_client.create_topic(Name=name)
+    topic = SnsTopic(arn=resp["TopicArn"], client=sns_client)
+    yield topic
+    with _safe_cleanup(f"SNS topic '{name}'"):
+        sns_client.delete_topic(TopicArn=topic.arn)

samstack/fixtures/sam_api.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+import pytest
+
+from samstack.fixtures._sam_container import _run_sam_service
+from samstack.settings import SamStackSettings
+
+
+@pytest.fixture(scope="session")
+def sam_api_extra_args() -> list[str]:
+    """
+    Extra CLI args appended to `sam local start-api` after the defaults.
+
+    Override in your conftest.py:
+
+        @pytest.fixture(scope="session")
+        def sam_api_extra_args() -> list[str]:
+            return ["--debug"]
+    """
+    return []
+
+
+@pytest.fixture(scope="session")
+def sam_api(
+    samstack_settings: SamStackSettings,
+    sam_build: None,
+    docker_network: str,
+    sam_api_extra_args: list[str],
+) -> Iterator[str]:
+    """
+    Start `sam local start-api` in Docker. Yields base URL http://127.0.0.1:{api_port}.
+    Logs written to {log_dir}/start-api.log.
+    """
+    with _run_sam_service(
+        settings=samstack_settings,
+        docker_network=docker_network,
+        subcommand="start-api",
+        port=samstack_settings.api_port,
+        warm_containers="LAZY",
+        settings_extra_args=samstack_settings.start_api_args,
+        fixture_extra_args=sam_api_extra_args,
+        log_filename="start-api.log",
+        wait_mode="http",
+    ) as endpoint:
+        yield endpoint

samstack/fixtures/sam_build.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from samstack._constants import LOCALSTACK_ACCESS_KEY, LOCALSTACK_SECRET_KEY
+from samstack._errors import SamBuildError
+from samstack._process import run_one_shot_container
+from samstack.fixtures._sam_container import DOCKER_SOCKET
+from samstack.settings import SamStackSettings
+
+
+def _add_gitignore_entry(project_root: Path, log_dir: str) -> None:
+    gitignore = project_root / ".gitignore"
+    entry = f"{log_dir}/"
+    if gitignore.exists():
+        content = gitignore.read_text()
+        if entry in content.splitlines():
+            return
+        gitignore.write_text(content.rstrip("\n") + f"\n{entry}\n")
+    else:
+        gitignore.write_text(f"{entry}\n")
+
+
+@pytest.fixture(scope="session")
+def sam_env_vars(samstack_settings: SamStackSettings) -> dict[str, dict[str, str]]:
+    """
+    Default environment variables injected into all Lambda functions at runtime.
+
+    Override in your conftest.py to add function-specific vars:
+
+        @pytest.fixture(scope="session")
+        def sam_env_vars(sam_env_vars):
+            sam_env_vars["MyFunction"] = {"MY_VAR": "value"}
+            return sam_env_vars
+    """
+    return {
+        "Parameters": {
+            "AWS_ENDPOINT_URL": "http://localstack:4566",
+            "AWS_DEFAULT_REGION": samstack_settings.region,
+            "AWS_ACCESS_KEY_ID": LOCALSTACK_ACCESS_KEY,
+            "AWS_SECRET_ACCESS_KEY": LOCALSTACK_SECRET_KEY,
+        }
+    }
+
+
+@pytest.fixture(scope="session")
+def sam_build(
+    samstack_settings: SamStackSettings,
+    sam_env_vars: dict[str, dict[str, str]],
+) -> None:
+    """
+    Run `sam build` in a one-shot Docker container. Runs once per test session.
+
+    The build output lands in {project_root}/.aws-sam/ and is reused by
+    sam_api and sam_lambda_endpoint fixtures.
+    """
+    log_dir = samstack_settings.project_root / samstack_settings.log_dir
+    log_dir.mkdir(parents=True, exist_ok=True)
+
+    # Write env vars JSON to a path accessible inside the SAM container
+    env_vars_path = log_dir / "env_vars.json"
+    env_vars_path.write_text(json.dumps(sam_env_vars, indent=2))
+
+    # Mount the project at its real host path so that Lambda containers
+    # created by SAM via the Docker socket can also mount it — Docker Desktop
+    # only shares /Users (and similar host paths), not paths inside containers.
+    host_path = str(samstack_settings.project_root)
+    build_cmd = [
+        "sam",
+        "build",
+        "--skip-pull-image",
+        "--template",
+        samstack_settings.template,
+        *samstack_settings.build_args,
+    ]
+    volumes = {
+        host_path: {"bind": host_path, "mode": "rw"},
+        DOCKER_SOCKET: {"bind": DOCKER_SOCKET, "mode": "rw"},
+    }
+
+    logs, exit_code = run_one_shot_container(
+        image=samstack_settings.sam_image,
+        command=build_cmd,
+        volumes=volumes,
+        working_dir=host_path,
+        environment={"DOCKER_DEFAULT_PLATFORM": samstack_settings.docker_platform},
+    )
+    if exit_code != 0:
+        raise SamBuildError(logs=logs)
+
+    if samstack_settings.add_gitignore:
+        _add_gitignore_entry(samstack_settings.project_root, samstack_settings.log_dir)

samstack/fixtures/sam_lambda.py

@@ -0,0 +1,74 @@
+from __future__ import annotations
+
+from collections.abc import Iterator
+from typing import TYPE_CHECKING
+
+import boto3
+import pytest
+
+if TYPE_CHECKING:
+    from mypy_boto3_lambda import LambdaClient
+
+from samstack._constants import LOCALSTACK_ACCESS_KEY, LOCALSTACK_SECRET_KEY
+from samstack.fixtures._sam_container import _run_sam_service
+from samstack.settings import SamStackSettings
+
+
+@pytest.fixture(scope="session")
+def sam_lambda_extra_args() -> list[str]:
+    """
+    Extra CLI args appended to `sam local start-lambda` after the defaults.
+
+    Override in your conftest.py:
+
+        @pytest.fixture(scope="session")
+        def sam_lambda_extra_args() -> list[str]:
+            return ["--debug"]
+    """
+    return []
+
+
+@pytest.fixture(scope="session")
+def sam_lambda_endpoint(
+    samstack_settings: SamStackSettings,
+    sam_build: None,
+    docker_network: str,
+    sam_lambda_extra_args: list[str],
+) -> Iterator[str]:
+    """
+    Start `sam local start-lambda` in Docker. Yields the endpoint URL
+    http://127.0.0.1:{lambda_port} for use with boto3 Lambda client.
+    Logs written to {log_dir}/start-lambda.log.
+    """
+    with _run_sam_service(
+        settings=samstack_settings,
+        docker_network=docker_network,
+        subcommand="start-lambda",
+        port=samstack_settings.lambda_port,
+        warm_containers="EAGER",
+        settings_extra_args=samstack_settings.start_lambda_args,
+        fixture_extra_args=sam_lambda_extra_args,
+        log_filename="start-lambda.log",
+        wait_mode="port",
+    ) as endpoint:
+        yield endpoint
+
+
+@pytest.fixture(scope="session")
+def lambda_client(
+    samstack_settings: SamStackSettings,
+    sam_lambda_endpoint: str,
+) -> LambdaClient:
+    """
+    Boto3 Lambda client pointed at the local SAM Lambda endpoint.
+
+    Use this to invoke functions directly without HTTP:
+        result = lambda_client.invoke(FunctionName="MyFunction", Payload=b"{}")
+    """
+    return boto3.client(
+        "lambda",
+        endpoint_url=sam_lambda_endpoint,
+        region_name=samstack_settings.region,
+        aws_access_key_id=LOCALSTACK_ACCESS_KEY,
+        aws_secret_access_key=LOCALSTACK_SECRET_KEY,
+    )

samstack/plugin.py

@@ -0,0 +1,94 @@
+"""
+Pytest plugin entry point for samstack.
+
+Registered via [project.entry-points."pytest11"] in pyproject.toml:
+    samstack = "samstack.plugin"
+
+This module registers all fixtures and provides the samstack_settings fixture
+by reading [tool.samstack] from the child project's pyproject.toml.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from samstack.fixtures.localstack import (
+    docker_network,
+    docker_network_name,
+    localstack_container,
+    localstack_endpoint,
+)
+from samstack.fixtures.resources import (
+    _dynamodb_resource,  # noqa: F401 — internal fixture, must be registered for pytest discovery
+    dynamodb_client,
+    dynamodb_table,
+    dynamodb_table_factory,
+    s3_bucket,
+    s3_bucket_factory,
+    s3_client,
+    sns_client,
+    sns_topic,
+    sns_topic_factory,
+    sqs_client,
+    sqs_queue,
+    sqs_queue_factory,
+)
+from samstack.fixtures.sam_api import sam_api, sam_api_extra_args
+from samstack.fixtures.sam_build import sam_build, sam_env_vars
+from samstack.fixtures.sam_lambda import (
+    lambda_client,
+    sam_lambda_endpoint,
+    sam_lambda_extra_args,
+)
+from samstack.settings import SamStackSettings, load_settings
+
+__all__ = [
+    "docker_network",
+    "docker_network_name",
+    "dynamodb_client",
+    "dynamodb_table",
+    "dynamodb_table_factory",
+    "lambda_client",
+    "localstack_container",
+    "localstack_endpoint",
+    "s3_bucket",
+    "s3_bucket_factory",
+    "s3_client",
+    "sam_api",
+    "sns_client",
+    "sns_topic",
+    "sns_topic_factory",
+    "sqs_client",
+    "sqs_queue",
+    "sqs_queue_factory",
+    "sam_api_extra_args",
+    "sam_build",
+    "sam_env_vars",
+    "sam_lambda_endpoint",
+    "sam_lambda_extra_args",
+    "samstack_settings",
+]
+
+
+@pytest.fixture(scope="session")
+def samstack_settings() -> SamStackSettings:
+    """
+    Load [tool.samstack] from the child project's pyproject.toml.
+
+    samstack searches upward from the current working directory for pyproject.toml.
+    Override this fixture to supply settings programmatically:
+
+        @pytest.fixture(scope="session")
+        def samstack_settings() -> SamStackSettings:
+            return SamStackSettings(sam_image="public.ecr.aws/sam/build-python3.13")
+    """
+    cwd = Path.cwd()
+    for parent in [cwd, *cwd.parents]:
+        candidate = parent / "pyproject.toml"
+        if candidate.exists():
+            return load_settings(parent)
+    raise FileNotFoundError(
+        "pyproject.toml not found. samstack requires [tool.samstack] in pyproject.toml."
+    )

samstack/resources/__init__.py

@@ -0,0 +1,6 @@
+from samstack.resources.dynamodb import DynamoTable
+from samstack.resources.s3 import S3Bucket
+from samstack.resources.sns import SnsTopic
+from samstack.resources.sqs import SqsQueue
+
+__all__ = ["DynamoTable", "S3Bucket", "SnsTopic", "SqsQueue"]