local-web-services-python-sdk 0.1.0__tar.gz

local_web_services_python_sdk-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,51 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Build wheel and sdist
+        run: uv build
+
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/local-web-services-python-sdk
+    permissions:
+      id-token: write   # required for OIDC trusted publishing
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

local_web_services_python_sdk-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+uv.lock
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# macOS
+.DS_Store
+
+# Temp
+*.tmp
+lws_testing_*/

local_web_services_python_sdk-0.1.0/Makefile

@@ -0,0 +1,17 @@
+.PHONY: install check lint format test
+
+install:
+	uv sync --all-groups
+
+lint:
+	uv run ruff check src/ tests/
+	uv run pylint src/
+
+format:
+	uv run black src/ tests/
+	uv run ruff check --fix src/ tests/
+
+test:
+	uv run pytest tests/ -v
+
+check: lint test

local_web_services_python_sdk-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,69 @@
+# 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/pyproject.toml

@@ -0,0 +1,83 @@
+[project]
+name = "local-web-services-python-sdk"
+version = "0.1.0"
+description = "Python testing SDK for local-web-services — in-process pytest fixtures and boto3 helpers"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+keywords = ["aws", "testing", "pytest", "boto3", "local", "dynamodb", "sqs", "s3", "mocking"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Testing",
+    "Framework :: Pytest",
+]
+dependencies = [
+    "httpx>=0.27.0",
+    "botocore>=1.34.0",
+    "pyyaml>=6.0",
+    "local-web-services>=0.17.2",
+]
+
+[project.optional-dependencies]
+pytest = [
+    "pytest>=8.0.0",
+]
+
+[project.urls]
+Homepage = "https://local-web-services.github.io/www"
+Repository = "https://github.com/local-web-services/local-web-services-sdk-python"
+Issues = "https://github.com/local-web-services/local-web-services-sdk-python/issues"
+
+[project.entry-points."pytest11"]
+lws_testing = "lws_testing.fixtures"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/lws_testing"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "boto3>=1.34.0",
+    "black>=24.0.0",
+    "ruff>=0.4.0",
+    "radon>=6.0.0",
+]
+
+[tool.black]
+line-length = 100
+target-version = ["py311"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W", "UP", "C90"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["lws_testing"]
+
+[tool.ruff.lint.mccabe]
+max-complexity = 10
+
+[tool.pylint."messages control"]
+disable = [
+    "E0401", "W0718", "R0801", "C0301", "C0302", "C0114", "C0115",
+    "R0903", "R0902", "R0913", "R0917", "R0904", "R0911", "R0914", "C0103",
+    "W0603", "W0621",
+]

local_web_services_python_sdk-0.1.0/src/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"]

local_web_services_python_sdk-0.1.0/src/lws_testing/_builders/__init__.py

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

local_web_services_python_sdk-0.1.0/src/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,
+        )

local_web_services_python_sdk-0.1.0/src/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

local_web_services_python_sdk-0.1.0/src/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)

local_web_services_python_sdk-0.1.0/src/lws_testing/_discovery/__init__.py

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