local-web-services-python-sdk 0.2.0__tar.gz → 0.19.0__tar.gz

local_web_services_python_sdk-0.19.0/Makefile

@@ -0,0 +1,78 @@
+.DEFAULT_GOAL := help
+
+# Pass SUITE=tests/e2e/<name> to target a single suite; defaults to all suites.
+SUITE ?= tests/e2e
+
+.PHONY: help install lint format format-check complexity cpd pylint \
+        test-unit test-architecture test-e2e-minimal test-e2e-guard test-e2e-sequence \
+        unit-test architecture-test e2e-test test check
+
+help: ## Show available targets
+	@grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | awk 'BEGIN {FS = ":.*?## "}; {printf "  %-24s %s\n", $$1, $$2}'
+
+install: ## Install dependencies
+	uv sync --all-groups
+
+# ── Static analysis ──────────────────────────────────────────────────────────
+
+lint: ## Run all static analysis: ruff, black --check, radon, cpd, pylint
+	uvx ruff check --quiet src tests
+	uvx black --check --quiet src tests
+	@output=$$(uvx radon cc src -a -nc); \
+	echo "$$output"; \
+	echo "$$output" | grep -qE '^ +[A-Z]' && { echo "FAIL: complexity grade C or worse detected"; exit 1; } || true
+	@output=$$(uvx --from pylint symilar -d 5 --ignore-imports --ignore-docstrings --ignore-signatures $$(find src -name "*.py")); \
+	echo "$$output" | tail -1; \
+	echo "$$output" | tail -1 | grep -q "duplicates=0 " || { echo "$$output"; exit 1; }
+	uvx --from pylint pylint src/lws_testing --recursive=y
+
+format: ## Auto-format code
+	uvx black src tests
+
+format-check: ## Check formatting without changing files
+	uvx black --check --quiet src tests
+
+complexity: ## Check cyclomatic complexity (grade B or better)
+	@output=$$(uvx radon cc src -a -nc); \
+	echo "$$output"; \
+	echo "$$output" | grep -qE '^ +[A-Z]' && { echo "FAIL: complexity grade C or worse detected"; exit 1; } || true
+
+cpd: ## Check for copy-pasted code (5+ similar lines)
+	@output=$$(uvx --from pylint symilar -d 5 --ignore-imports --ignore-docstrings --ignore-signatures $$(find src -name "*.py")); \
+	echo "$$output" | tail -1; \
+	echo "$$output" | tail -1 | grep -q "duplicates=0 " || { echo "$$output"; exit 1; }
+
+pylint: ## Run pylint
+	uvx --from pylint pylint src/lws_testing --recursive=y
+
+# ── Tests ─────────────────────────────────────────────────────────────────────
+
+test-unit: ## Run unit tests
+	uv run pytest -q tests/unit
+
+test-architecture: ## Run architecture constraint tests
+	uv run pytest -q tests/architecture
+
+# Pass SUITE=tests/e2e/<name> on the command line to target one suite.
+test-e2e-minimal: ## Run @minimal e2e scenarios (requires Docker)
+	uv run pytest $(SUITE) -v -m minimal --junitxml=test-results/junit-minimal.xml
+
+test-e2e-guard: ## Run @guard e2e scenarios (requires Docker)
+	uv run pytest $(SUITE) -v -m guard --junitxml=test-results/junit-guard.xml
+
+test-e2e-sequence: ## Run @sequence e2e scenarios (requires Docker)
+	uv run pytest $(SUITE) -v -m sequence --junitxml=test-results/junit-sequence.xml
+
+# ── Aliases (backward-compatible) ─────────────────────────────────────────────
+
+unit-test: test-unit ## Alias for test-unit
+
+architecture-test: test-architecture ## Alias for test-architecture
+
+e2e-test: test-e2e-minimal test-e2e-guard test-e2e-sequence ## Run all e2e scenarios (requires Docker)
+
+test: test-unit test-architecture ## Run all non-e2e tests
+
+# ── Composite ─────────────────────────────────────────────────────────────────
+
+check: lint test-unit test-architecture ## Run all checks (what CI runs)

local_web_services_python_sdk-0.19.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: local-web-services-python-sdk
+Version: 0.19.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
+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,faking,local,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.19.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: pytest
+Requires-Dist: pytest>=8.0.0; extra == 'pytest'
+Description-Content-Type: text/markdown
+
+# local-web-services-python-sdk
+
+Python testing SDK for [local-web-services](https://local-web-services.github.io) — starts
+in-process AWS service emulators and provides pre-configured `boto3` clients that point at them.
+Your production code works unchanged: the SDK sets `AWS_ENDPOINT_URL_*` environment variables
+that boto3 picks up automatically.
+
+## Installation
+
+```bash
+pip install local-web-services-python-sdk
+# or
+uv add local-web-services-python-sdk
+```
+
+Requires Python 3.9+ and `boto3`.
+
+## Quick start
+
+```python
+from lws_testing import LwsSession, DynamoTable, SqsQueue, S3Bucket
+
+with LwsSession(
+    DynamoTable("Orders", hash_key="id"),
+    SqsQueue("OrderQueue"),
+    S3Bucket("my-bucket"),
+) as session:
+    # Get a boto3 client pointing at the local emulator
+    dynamo = session.client("dynamodb")
+    dynamo.put_item(TableName="Orders", Item={"id": {"S": "1"}, "status": {"S": "pending"}})
+
+    item = dynamo.get_item(TableName="Orders", Key={"id": {"S": "1"}})
+    assert item["Item"]["status"]["S"] == "pending"
+
+    # SQS
+    sqs = session.client("sqs")
+    queue_url = session.queue_url("OrderQueue")
+    sqs.send_message(QueueUrl=queue_url, MessageBody="hello")
+
+    # S3
+    s3 = session.client("s3")
+    s3.put_object(Bucket="my-bucket", Key="file.txt", Body=b"hello")
+```
+
+## Auto-discover resources from CDK / Terraform
+
+```python
+# Read resource definitions from a CDK project
+with LwsSession.from_cdk("../my-cdk-project") as session:
+    dynamo = session.client("dynamodb")
+    ...
+
+# Read resource definitions from a Terraform project
+with LwsSession.from_hcl("../my-terraform-project") as session:
+    s3 = session.client("s3")
+    ...
+```
+
+## Resource specs
+
+Declare the resources your test needs up front so LwsSession creates them before the test runs:
+
+| Spec | Description |
+|---|---|
+| `DynamoTable(name, hash_key, sort_key=None)` | PAY_PER_REQUEST DynamoDB table |
+| `SqsQueue(name)` | Standard SQS queue |
+| `S3Bucket(name)` | S3 bucket |
+| `SnsTopic(name)` | SNS topic |
+| `SsmParameter(name, value, type="String")` | SSM Parameter Store entry |
+| `Secret(name, value)` | Secrets Manager secret |
+| `StateMachine(name, definition)` | Step Functions state machine |
+
+## 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
+from lws_testing import DynamoTable, SqsQueue
+
+@pytest.fixture(scope="session")
+def lws_session_spec():
+    return [
+        DynamoTable("Orders", hash_key="id"),
+        SqsQueue("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"}})
+    item = client.get_item(TableName="Orders", Key={"id": {"S": "42"}})
+    assert item["Item"]["id"]["S"] == "42"
+```
+
+## Supported services
+
+All 20 services are available via `session.client(service_name)`:
+
+| Service | `session.client(...)` name |
+|---|---|
+| DynamoDB | `"dynamodb"` |
+| SQS | `"sqs"` |
+| S3 | `"s3"` |
+| SNS | `"sns"` |
+| EventBridge | `"events"` |
+| Step Functions | `"stepfunctions"` |
+| Cognito IDP | `"cognito-idp"` |
+| Lambda | `"lambda"` |
+| API Gateway | `"apigateway"` |
+| RDS | `"rds"` |
+| DocumentDB | `"docdb"` |
+| SSM Parameter Store | `"ssm"` |
+| Secrets Manager | `"secretsmanager"` |
+| ElastiCache | `"elasticache"` |
+| Neptune | `"neptune"` |
+| MemoryDB | `"memorydb"` |
+| Glacier | `"glacier"` |
+| Elasticsearch | `"es"` |
+| OpenSearch | `"opensearch"` |
+| S3 Tables | `"s3tables"` |
+
+## How it works
+
+`LwsSession` picks a random free base port and starts each service emulator in a background
+thread within the test process. It sets `AWS_ENDPOINT_URL_<SERVICE>` (and stub credentials) in
+the current process environment so that any boto3 client created during the test automatically
+talks to the local emulator. On `__exit__` the servers are stopped and the environment is restored.
+
+## License
+
+MIT

local_web_services_python_sdk-0.19.0/README.md

@@ -0,0 +1,137 @@
+# local-web-services-python-sdk
+
+Python testing SDK for [local-web-services](https://local-web-services.github.io) — starts
+in-process AWS service emulators and provides pre-configured `boto3` clients that point at them.
+Your production code works unchanged: the SDK sets `AWS_ENDPOINT_URL_*` environment variables
+that boto3 picks up automatically.
+
+## Installation
+
+```bash
+pip install local-web-services-python-sdk
+# or
+uv add local-web-services-python-sdk
+```
+
+Requires Python 3.9+ and `boto3`.
+
+## Quick start
+
+```python
+from lws_testing import LwsSession, DynamoTable, SqsQueue, S3Bucket
+
+with LwsSession(
+    DynamoTable("Orders", hash_key="id"),
+    SqsQueue("OrderQueue"),
+    S3Bucket("my-bucket"),
+) as session:
+    # Get a boto3 client pointing at the local emulator
+    dynamo = session.client("dynamodb")
+    dynamo.put_item(TableName="Orders", Item={"id": {"S": "1"}, "status": {"S": "pending"}})
+
+    item = dynamo.get_item(TableName="Orders", Key={"id": {"S": "1"}})
+    assert item["Item"]["status"]["S"] == "pending"
+
+    # SQS
+    sqs = session.client("sqs")
+    queue_url = session.queue_url("OrderQueue")
+    sqs.send_message(QueueUrl=queue_url, MessageBody="hello")
+
+    # S3
+    s3 = session.client("s3")
+    s3.put_object(Bucket="my-bucket", Key="file.txt", Body=b"hello")
+```
+
+## Auto-discover resources from CDK / Terraform
+
+```python
+# Read resource definitions from a CDK project
+with LwsSession.from_cdk("../my-cdk-project") as session:
+    dynamo = session.client("dynamodb")
+    ...
+
+# Read resource definitions from a Terraform project
+with LwsSession.from_hcl("../my-terraform-project") as session:
+    s3 = session.client("s3")
+    ...
+```
+
+## Resource specs
+
+Declare the resources your test needs up front so LwsSession creates them before the test runs:
+
+| Spec | Description |
+|---|---|
+| `DynamoTable(name, hash_key, sort_key=None)` | PAY_PER_REQUEST DynamoDB table |
+| `SqsQueue(name)` | Standard SQS queue |
+| `S3Bucket(name)` | S3 bucket |
+| `SnsTopic(name)` | SNS topic |
+| `SsmParameter(name, value, type="String")` | SSM Parameter Store entry |
+| `Secret(name, value)` | Secrets Manager secret |
+| `StateMachine(name, definition)` | Step Functions state machine |
+
+## 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
+from lws_testing import DynamoTable, SqsQueue
+
+@pytest.fixture(scope="session")
+def lws_session_spec():
+    return [
+        DynamoTable("Orders", hash_key="id"),
+        SqsQueue("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"}})
+    item = client.get_item(TableName="Orders", Key={"id": {"S": "42"}})
+    assert item["Item"]["id"]["S"] == "42"
+```
+
+## Supported services
+
+All 20 services are available via `session.client(service_name)`:
+
+| Service | `session.client(...)` name |
+|---|---|
+| DynamoDB | `"dynamodb"` |
+| SQS | `"sqs"` |
+| S3 | `"s3"` |
+| SNS | `"sns"` |
+| EventBridge | `"events"` |
+| Step Functions | `"stepfunctions"` |
+| Cognito IDP | `"cognito-idp"` |
+| Lambda | `"lambda"` |
+| API Gateway | `"apigateway"` |
+| RDS | `"rds"` |
+| DocumentDB | `"docdb"` |
+| SSM Parameter Store | `"ssm"` |
+| Secrets Manager | `"secretsmanager"` |
+| ElastiCache | `"elasticache"` |
+| Neptune | `"neptune"` |
+| MemoryDB | `"memorydb"` |
+| Glacier | `"glacier"` |
+| Elasticsearch | `"es"` |
+| OpenSearch | `"opensearch"` |
+| S3 Tables | `"s3tables"` |
+
+## How it works
+
+`LwsSession` picks a random free base port and starts each service emulator in a background
+thread within the test process. It sets `AWS_ENDPOINT_URL_<SERVICE>` (and stub credentials) in
+the current process environment so that any boto3 client created during the test automatically
+talks to the local emulator. On `__exit__` the servers are stopped and the environment is restored.
+
+## License
+
+MIT

local_web_services_python_sdk-0.19.0/pyproject.toml

@@ -0,0 +1,103 @@
+[project]
+name = "local-web-services-python-sdk"
+version = "0.19.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", "faking"]
+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.19.0",
+]
+
+[project.optional-dependencies]
+pytest = [
+    "pytest>=8.0.0",
+]
+
+[project.urls]
+Homepage = "https://local-web-services.github.io"
+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"
+addopts = "-qq --no-header --disable-warnings"
+markers = [
+    "internal: scenarios tagged @internal in Gherkin (excluded from standard test runs)",
+    "lifecycle: scenarios tagged @lifecycle in Gherkin (require internal lifecycle control)",
+    "capacity: scenarios tagged @capacity in Gherkin (require internal capacity control)",
+    "guard: scenarios tagged @guard in Gherkin (guard violation / negative outcome)",
+    "sequence: scenarios tagged @sequence in Gherkin (multi-action chain)",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-asyncio>=0.23.0",
+    "pytest-bdd>=8.1.0",
+    "boto3>=1.34.0",
+    "black>=24.0.0",
+    "ruff>=0.4.0",
+    "radon>=6.0.0",
+    "lws-arch-tests",
+    "agency-pytest-agent-reporter>=0.1.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.per-file-ignores]
+"tests/e2e/**/given/*.py" = ["E501"]
+"tests/e2e/**/when/*.py" = ["E501"]
+"tests/e2e/**/then/*.py" = ["E501"]
+
+[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", "C0415", "C0116", "W0212",
+]
+
+[tool.uv.sources]
+local-web-services = { path = "../core", editable = true }
+lws-arch-tests = { path = "../arch_tests", editable = true }

local_web_services_python_sdk-0.19.0/src/lws_testing/__init__.py

@@ -0,0 +1,53 @@
+"""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, DynamoTable, SqsQueue
+
+    # Typed resource specs (recommended)
+    with LwsSession(
+        DynamoTable("Orders", hash_key="id"),
+        SqsQueue("OrderQueue"),
+    ) as session: ...
+
+    # Auto-detect CDK or HCL project in current directory
+    with LwsSession.from_cdk("../") as session: ...
+    with LwsSession.from_hcl("../") as session: ...
+
+    # Legacy dict-based resource declaration (still supported)
+    with LwsSession(
+        tables=[{"name": "Orders", "partition_key": "id"}],
+        queues=["OrderQueue"],
+        buckets=["ReceiptsBucket"],
+    ) as session: ...
+"""
+
+from __future__ import annotations
+
+from lws_testing._spec import (
+    DynamoTable,
+    S3Bucket,
+    Secret,
+    SnsTopic,
+    SqsQueue,
+    SsmParameter,
+    StateMachine,
+)
+from lws_testing.services import LifecycleDwell, Service
+from lws_testing.session import LwsSession
+
+__all__ = [
+    "LwsSession",
+    "DynamoTable",
+    "SqsQueue",
+    "S3Bucket",
+    "SnsTopic",
+    "SsmParameter",
+    "Secret",
+    "StateMachine",
+    "Service",
+    "LifecycleDwell",
+]

local_web_services_python_sdk-0.19.0/src/lws_testing/_builders/capacity.py

@@ -0,0 +1,63 @@
+"""Fluent builder for configuring AWS service capacity."""
+
+from __future__ import annotations
+
+import httpx
+
+
+class CapacityBuilder:
+    """Fluent builder for AWS service capacity configuration.
+
+    Usage::
+
+        session.capacity("stepfunctions").exhaust().apply()
+        session.capacity("lambda").exhaust().apply()
+    """
+
+    def __init__(self, service: str, mgmt_port: int) -> None:
+        self._service = service
+        self._mgmt_port = mgmt_port
+        self._config: dict = {}
+
+    def exhaust(self) -> CapacityBuilder:
+        """Set slot count to zero (no capacity available)."""
+        self._config["slots"] = 0
+        return self
+
+    def slots(self, n: int) -> CapacityBuilder:
+        """Set slot count to a specific value."""
+        self._config["slots"] = int(n)
+        return self
+
+    def unlimited(self) -> CapacityBuilder:
+        """Remove slot limit (restore unlimited capacity)."""
+        self._config["slots"] = None
+        return self
+
+    def apply(self) -> None:
+        """Push the capacity configuration to the management API."""
+        httpx.post(
+            f"http://127.0.0.1:{self._mgmt_port}/_ldk/capacity",
+            json={self._service: self._config},
+            timeout=5.0,
+        )
+
+    def is_exhausted(self) -> bool:
+        """Return True if the service currently has zero capacity."""
+        resp = httpx.get(
+            f"http://127.0.0.1:{self._mgmt_port}/_ldk/capacity",
+            timeout=5.0,
+        )
+        data = resp.json()
+        capacity = data.get("capacity", data)
+        svc = capacity.get(self._service, {})
+        slots = svc.get("slots")
+        return slots is not None and slots == 0
+
+    def clear(self) -> None:
+        """Restore unlimited capacity for this service."""
+        httpx.post(
+            f"http://127.0.0.1:{self._mgmt_port}/_ldk/capacity",
+            json={self._service: {"slots": None}},
+            timeout=5.0,
+        )