local-web-services-python-sdk 0.1.0__py3-none-any.whl

local_web_services_python_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: local-web-services-python-sdk
+Version: 0.1.0
+Summary: Python testing SDK for local-web-services — in-process pytest fixtures and boto3 helpers
+Project-URL: Homepage, https://local-web-services.github.io/www
+Project-URL: Repository, https://github.com/local-web-services/local-web-services-sdk-python
+Project-URL: Issues, https://github.com/local-web-services/local-web-services-sdk-python/issues
+License-Expression: MIT
+Keywords: aws,boto3,dynamodb,local,mocking,pytest,s3,sqs,testing
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Pytest
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: botocore>=1.34.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: local-web-services>=0.17.2
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: pytest
+Requires-Dist: pytest>=8.0.0; extra == 'pytest'
+Description-Content-Type: text/markdown
+
+# local-web-services-testing
+
+Python testing SDK for [local-web-services](https://github.com/local-web-services/local-web-services) — in-process pytest fixtures and boto3 helpers for testing AWS applications without needing a running `ldk dev`.
+
+## Installation
+
+```bash
+pip install local-web-services-python-sdk
+# or
+uv add local-web-services-python-sdk
+```
+
+## Quick start
+
+```python
+from lws_testing import LwsSession
+
+# Auto-discover resources from a CDK project
+with LwsSession.from_cdk("../my-cdk-project") as session:
+    dynamo = session.client("dynamodb")
+    dynamo.put_item(TableName="Orders", Item={"id": {"S": "1"}})
+
+# Auto-discover resources from a Terraform project
+with LwsSession.from_hcl("../my-terraform-project") as session:
+    s3 = session.client("s3")
+    s3.put_object(Bucket="my-bucket", Key="test.txt", Body=b"hello")
+
+# Explicit resource declaration
+with LwsSession(
+    tables=[{"name": "Orders", "partition_key": "id"}],
+    queues=["OrderQueue"],
+    buckets=["ReceiptsBucket"],
+) as session:
+    table = session.dynamodb("Orders")
+    table.put({"id": {"S": "1"}, "status": {"S": "pending"}})
+    items = table.scan()
+    assert len(items) == 1
+```
+
+## pytest integration
+
+The package registers pytest fixtures automatically via the `pytest11` entry point. Add a session fixture to your `conftest.py`:
+
+```python
+# conftest.py
+import pytest
+
+@pytest.fixture(scope="session")
+def lws_session_spec():
+    return {
+        "tables": [{"name": "Orders", "partition_key": "id"}],
+        "queues": ["OrderQueue"],
+    }
+```
+
+Then use the `lws_session` fixture in your tests:
+
+```python
+def test_create_order(lws_session):
+    client = lws_session.client("dynamodb")
+    client.put_item(TableName="Orders", Item={"id": {"S": "42"}})
+
+    table = lws_session.dynamodb("Orders")
+    table.assert_item_exists({"id": {"S": "42"}})
+```
+
+## License
+
+MIT

local_web_services_python_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,21 @@
+lws_testing/__init__.py,sha256=CF0kQuwZlj6Ab1bAuZWBBxV91ztYX9RqoBny8n9jPI4,715
+lws_testing/_logs.py,sha256=RqIhgQeew06fjihCdFKTa-KtOC2g3ZHqDLVNqBaIi7c,4244
+lws_testing/fixtures.py,sha256=ayht4LVBh_8V-hc1aFlYD7jJUVxK2PTlqSZjmHbkX-k,3042
+lws_testing/session.py,sha256=jc6lHkhjtULFULWT8QZ-QMZ2uMobfJpPxpE61H3Lhf0,12827
+lws_testing/_builders/__init__.py,sha256=HttkUvWQTrEoF9KZCc75qf86vtqynvQNZVrKdO6z9gc,62
+lws_testing/_builders/chaos.py,sha256=OeWeyJ5nMrUkmO065Pzok-kycfAHDYIDyccT9MfxPkY,1899
+lws_testing/_builders/iam.py,sha256=vuKUoiHlIcrABIivtS3p7vQOBC_mjQa3c-q_EizRZCA,4184
+lws_testing/_builders/mock.py,sha256=MTfUR9rkK7FA1Wt34wSFelKIpng8GeJizCCOWjaOehE,3284
+lws_testing/_discovery/__init__.py,sha256=cLKqSotYqZfhK6PImCtn9dx7DqYytJxYfxNElsUKJ-Y,52
+lws_testing/_discovery/cdk.py,sha256=KoCDTHCh4qgpbiKrmlByhY3mW1UgSUm4Ks-yynSTNTw,3587
+lws_testing/_discovery/hcl.py,sha256=-DrqJRbGgdFkeIMQvNxRiyBzpM88F80QMLwHKC0PZd8,6269
+lws_testing/_resources/__init__.py,sha256=omtQNKUO7jAlH1GhwgqYMgkkYTDI_BXr5RvfCl4JDFs,68
+lws_testing/_resources/dynamodb.py,sha256=_H_K7sQLAvilhcYJgvANETzBdogt-SMA0z89XImJdLY,2565
+lws_testing/_resources/s3.py,sha256=d9EQAIQ6qPw1jdF5A9arjskwmj9SehkzdE9OCWHgzkQ,2670
+lws_testing/_resources/sqs.py,sha256=N2CFWOHxQjjMzB3-_m1M1qczaBCzqbL8smr-E5TL8tU,2428
+lws_testing/_transport/__init__.py,sha256=o87a1hyGHtaDNaR8y9BRRbe5RiQqXjLj0zATpaNowqs,62
+lws_testing/_transport/inprocess.py,sha256=hFt-DokOREUqRbaHyYb8D3jeP8qLcVMtvg0o8uqUb5A,9821
+local_web_services_python_sdk-0.1.0.dist-info/METADATA,sha256=ZwnWJkV0lzqH07mONnAJ_-S-tq7U17Bq4DBVIzZvI7Y,3082
+local_web_services_python_sdk-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+local_web_services_python_sdk-0.1.0.dist-info/entry_points.txt,sha256=rL_6OHSdYlP7fXMZWJg1R_O_DfqSdbg2ZYaU6dLh4lM,46
+local_web_services_python_sdk-0.1.0.dist-info/RECORD,,

local_web_services_python_sdk-0.1.0.dist-info/WHEEL

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

local_web_services_python_sdk-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[pytest11]
+lws_testing = lws_testing.fixtures

lws_testing/__init__.py

@@ -0,0 +1,26 @@
+"""local-web-services testing SDK.
+
+In-process pytest fixtures and boto3 helpers for testing AWS applications
+against real LWS service implementations without needing a running ldk dev.
+
+Usage::
+
+    from lws_testing import LwsSession
+
+    # Auto-detect CDK or HCL project in current directory
+    with LwsSession.from_cdk("../") as session: ...
+    with LwsSession.from_hcl("../") as session: ...
+
+    # Explicit resource declaration
+    with LwsSession(
+        tables=[{"name": "Orders", "partition_key": "id"}],
+        queues=["OrderQueue"],
+        buckets=["ReceiptsBucket"],
+    ) as session: ...
+"""
+
+from __future__ import annotations
+
+from lws_testing.session import LwsSession
+
+__all__ = ["LwsSession"]

lws_testing/_builders/__init__.py

@@ -0,0 +1 @@
+"""Fluent builders for mock, chaos, and IAM configuration."""

lws_testing/_builders/chaos.py

@@ -0,0 +1,56 @@
+"""Fluent builder for configuring chaos engineering rules."""
+
+from __future__ import annotations
+
+import httpx
+
+
+class ChaosBuilder:
+    """Fluent builder for AWS service chaos configuration.
+
+    Usage::
+
+        session.chaos("dynamodb").error_rate(0.3).latency(min_ms=50, max_ms=200).apply()
+    """
+
+    def __init__(self, service: str, mgmt_port: int) -> None:
+        self._service = service
+        self._mgmt_port = mgmt_port
+        self._config: dict = {"enabled": True}
+
+    def error_rate(self, rate: float) -> "ChaosBuilder":
+        """Set the fraction of requests that return an error (0.0–1.0)."""
+        self._config["error_rate"] = float(rate)
+        return self
+
+    def latency(self, min_ms: int = 0, max_ms: int = 0) -> "ChaosBuilder":
+        """Inject artificial latency into responses."""
+        self._config["latency_min_ms"] = min_ms
+        self._config["latency_max_ms"] = max_ms
+        return self
+
+    def connection_reset_rate(self, rate: float) -> "ChaosBuilder":
+        """Set the fraction of requests that receive a connection reset (0.0–1.0)."""
+        self._config["connection_reset_rate"] = float(rate)
+        return self
+
+    def timeout_rate(self, rate: float) -> "ChaosBuilder":
+        """Set the fraction of requests that time out (0.0–1.0)."""
+        self._config["timeout_rate"] = float(rate)
+        return self
+
+    def apply(self) -> None:
+        """Push the chaos configuration to the management API."""
+        httpx.post(
+            f"http://127.0.0.1:{self._mgmt_port}/_ldk/chaos",
+            json={self._service: self._config},
+            timeout=5.0,
+        )
+
+    def clear(self) -> None:
+        """Disable chaos for this service."""
+        httpx.post(
+            f"http://127.0.0.1:{self._mgmt_port}/_ldk/chaos",
+            json={self._service: {"enabled": False, "error_rate": 0.0}},
+            timeout=5.0,
+        )

lws_testing/_builders/iam.py

@@ -0,0 +1,125 @@
+"""Fluent builder for configuring IAM authorization at runtime."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class IamBuilder:
+    """Fluent builder for runtime IAM auth configuration.
+
+    Usage::
+
+        # Switch to enforce mode
+        session.iam.mode("enforce").apply()
+
+        # Register a read-only identity
+        session.iam.identity("readonly").allow(["dynamodb:GetItem"]).apply()
+    """
+
+    def __init__(self, mgmt_port: int) -> None:
+        self._mgmt_port = mgmt_port
+        self._updates: dict[str, Any] = {}
+        self._identities: dict[str, Any] = {}
+
+    def mode(self, mode: str) -> "IamBuilder":
+        """Set the global IAM auth mode (``"enforce"``, ``"audit"``, ``"disabled"``)."""
+        self._updates["mode"] = mode
+        return self
+
+    def default_identity(self, name: str) -> "IamBuilder":
+        """Set the default identity used when no identity header is present."""
+        self._updates["default_identity"] = name
+        return self
+
+    def identity(self, name: str) -> "_IdentityBuilder":
+        """Start configuring a named identity."""
+        return _IdentityBuilder(self, name)
+
+    def _register_identity(self, name: str, config: dict[str, Any]) -> None:
+        self._identities[name] = config
+
+    def apply(self) -> None:
+        """Push all pending IAM configuration to the management API."""
+        payload: dict[str, Any] = dict(self._updates)
+        if self._identities:
+            payload["identities"] = self._identities
+        httpx.post(
+            f"http://127.0.0.1:{self._mgmt_port}/_ldk/iam-auth",
+            json=payload,
+            timeout=5.0,
+        )
+        self._updates = {}
+        self._identities = {}
+
+
+class _IdentityBuilder:
+    """Configure a single named IAM identity."""
+
+    def __init__(self, parent: IamBuilder, name: str) -> None:
+        self._parent = parent
+        self._name = name
+        self._inline_policies: list[dict[str, Any]] = []
+        self._boundary: dict[str, Any] | None = None
+
+    def allow(self, actions: list[str], resource: str = "*") -> "_IdentityBuilder":
+        """Add an Allow statement to this identity's inline policy."""
+        self._inline_policies.append(
+            {
+                "name": f"inline-{len(self._inline_policies)}",
+                "document": {
+                    "Version": "2012-10-17",
+                    "Statement": [
+                        {
+                            "Effect": "Allow",
+                            "Action": actions,
+                            "Resource": resource,
+                        }
+                    ],
+                },
+            }
+        )
+        return self
+
+    def deny(self, actions: list[str], resource: str = "*") -> "_IdentityBuilder":
+        """Add an explicit Deny statement to this identity's inline policy."""
+        self._inline_policies.append(
+            {
+                "name": f"inline-deny-{len(self._inline_policies)}",
+                "document": {
+                    "Version": "2012-10-17",
+                    "Statement": [
+                        {
+                            "Effect": "Deny",
+                            "Action": actions,
+                            "Resource": resource,
+                        }
+                    ],
+                },
+            }
+        )
+        return self
+
+    def boundary(self, actions: list[str], resource: str = "*") -> "_IdentityBuilder":
+        """Set a permissions boundary for this identity."""
+        self._boundary = {
+            "Version": "2012-10-17",
+            "Statement": [
+                {
+                    "Effect": "Allow",
+                    "Action": actions,
+                    "Resource": resource,
+                }
+            ],
+        }
+        return self
+
+    def apply(self) -> "IamBuilder":
+        """Register the identity and return the parent builder for chaining."""
+        config: dict[str, Any] = {"inline_policies": self._inline_policies}
+        if self._boundary is not None:
+            config["boundary_policy"] = self._boundary
+        self._parent._register_identity(self._name, config)
+        return self._parent

lws_testing/_builders/mock.py

@@ -0,0 +1,107 @@
+"""Fluent builder for configuring AWS operation mocks."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class MockBuilder:
+    """Fluent builder for AWS service mock responses.
+
+    Usage::
+
+        session.mock("dynamodb").operation("PutItem").respond(
+            status=500,
+            body={"__type": "ProvisionedThroughputExceededException"},
+        )
+    """
+
+    def __init__(self, service: str, mgmt_port: int) -> None:
+        self._service = service
+        self._mgmt_port = mgmt_port
+        self._rules: list[dict[str, Any]] = []
+
+    def operation(self, operation_name: str) -> "_MockRuleBuilder":
+        """Start building a mock rule for *operation_name*."""
+        return _MockRuleBuilder(self, operation_name)
+
+    def _add_rule(self, rule: dict[str, Any]) -> "MockBuilder":
+        self._rules.append(rule)
+        self._apply()
+        return self
+
+    def _apply(self) -> None:
+        """Push the current rules to the management API."""
+        httpx.post(
+            f"http://127.0.0.1:{self._mgmt_port}/_ldk/aws-mock",
+            json={self._service: {"enabled": True, "rules": self._rules}},
+            timeout=5.0,
+        )
+
+    def clear(self) -> None:
+        """Remove all mock rules for this service."""
+        self._rules = []
+        httpx.post(
+            f"http://127.0.0.1:{self._mgmt_port}/_ldk/aws-mock",
+            json={self._service: {"enabled": False, "rules": []}},
+            timeout=5.0,
+        )
+
+
+class _MockRuleBuilder:
+    """Intermediate builder — configure a single mock rule."""
+
+    def __init__(self, parent: MockBuilder, operation: str) -> None:
+        self._parent = parent
+        self._operation = operation
+        self._match_headers: dict[str, str] = {}
+
+    def with_header(self, name: str, value: str) -> "_MockRuleBuilder":
+        """Add an additional header match constraint."""
+        self._match_headers[name] = value
+        return self
+
+    def respond(
+        self,
+        status: int = 200,
+        body: str | dict[str, Any] = "",
+        content_type: str = "application/json",
+        delay_ms: int = 0,
+    ) -> MockBuilder:
+        """Set the response and register the rule.
+
+        Args:
+            status: HTTP status code to return.
+            body: Response body (dict will be JSON-encoded).
+            content_type: Response Content-Type header.
+            delay_ms: Artificial delay before responding.
+        """
+        import json
+
+        if isinstance(body, dict):
+            body_str = json.dumps(body)
+        else:
+            body_str = body
+
+        rule: dict[str, Any] = {
+            "operation": self._operation,
+            "match_headers": self._match_headers,
+            "response": {
+                "status": status,
+                "content_type": content_type,
+                "delay_ms": delay_ms,
+            },
+        }
+        if body_str:
+            rule["response"]["body"] = body_str
+
+        return self._parent._add_rule(rule)
+
+    def error(self, error_type: str, message: str = "", status: int = 400) -> MockBuilder:
+        """Respond with a structured AWS error."""
+        import json
+
+        body = json.dumps({"__type": error_type, "message": message})
+        return self.respond(status=status, body=body)

lws_testing/_discovery/__init__.py

@@ -0,0 +1 @@
+"""Resource discovery from CDK and HCL projects."""

lws_testing/_discovery/cdk.py

@@ -0,0 +1,115 @@
+"""Discover AWS resources from a CDK cloud assembly (cdk.out/)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+
+def discover(project_dir: Path) -> dict[str, Any]:
+    """Parse the CDK cloud assembly and return a resource spec dict.
+
+    Reads ``{project_dir}/cdk.out/`` (runs ``cdk synth`` first if absent is
+    acceptable — callers should run ``npx cdk synth`` beforehand).
+
+    Returns a dict compatible with :class:`~lws_testing.LwsSession` kwargs:
+    ``tables``, ``queues``, ``buckets``, ``topics``, ``state_machines``,
+    ``secrets``, ``parameters``.
+    """
+    from lws.parser.assembly import parse_assembly
+
+    cdk_out = project_dir / "cdk.out"
+    if not cdk_out.exists():
+        raise FileNotFoundError(
+            f"CDK cloud assembly not found at {cdk_out}. "
+            "Run 'npx cdk synth' in your CDK project first."
+        )
+
+    model = parse_assembly(cdk_out)
+
+    tables = _extract_tables(model.tables)
+    queues = _extract_queues(model.queues)
+    buckets = [b.name for b in model.buckets]
+    topics = [{"name": t.name, "arn": t.topic_arn} for t in model.topics]
+    state_machines = _extract_state_machines(model.state_machines)
+    parameters = _extract_parameters(model.ssm_parameters)
+    secrets = _extract_secrets(model.secrets)
+
+    return {
+        "tables": tables,
+        "queues": queues,
+        "buckets": buckets,
+        "topics": topics,
+        "state_machines": state_machines,
+        "parameters": parameters,
+        "secrets": secrets,
+    }
+
+
+def _extract_tables(dynamo_tables: list[Any]) -> list[dict[str, Any]]:
+    """Convert DynamoTable models to table spec dicts."""
+    result = []
+    for table in dynamo_tables:
+        spec: dict[str, Any] = {"name": table.name}
+        for key in table.key_schema:
+            key_type = key.get("KeyType", "")
+            attr_name = key.get("AttributeName", "")
+            if key_type == "HASH":
+                spec["partition_key"] = attr_name
+            elif key_type == "RANGE":
+                spec["sort_key"] = attr_name
+        if "partition_key" not in spec:
+            # Skip tables without a parseable partition key
+            continue
+        result.append(spec)
+    return result
+
+
+def _extract_queues(sqs_queues: list[Any]) -> list[dict[str, Any]]:
+    """Convert SqsQueue models to queue spec dicts."""
+    return [
+        {
+            "name": q.name,
+            "is_fifo": q.is_fifo,
+            "visibility_timeout": q.visibility_timeout,
+            "content_based_dedup": q.content_based_dedup,
+        }
+        for q in sqs_queues
+    ]
+
+
+def _extract_state_machines(state_machines: list[Any]) -> list[dict[str, Any]]:
+    """Convert StateMachine models to state machine spec dicts."""
+    return [
+        {
+            "name": sm.name,
+            "definition": sm.definition,
+            "role_arn": sm.role_arn,
+        }
+        for sm in state_machines
+    ]
+
+
+def _extract_parameters(ssm_parameters: list[Any]) -> list[dict[str, Any]]:
+    """Convert SsmParameter models to parameter spec dicts."""
+    return [
+        {
+            "name": p.name,
+            "value": p.value,
+            "type": p.type,
+            "description": p.description,
+        }
+        for p in ssm_parameters
+    ]
+
+
+def _extract_secrets(secrets: list[Any]) -> list[dict[str, Any]]:
+    """Convert SmSecret models to secret spec dicts."""
+    return [
+        {
+            "name": s.name,
+            "description": s.description,
+            "secret_string": s.secret_string or "",
+        }
+        for s in secrets
+    ]