semblance 0.2.2__tar.gz → 0.3.0__tar.gz

{semblance-0.2.2/src/semblance.egg-info → semblance-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: semblance
-Version: 0.2.2
+Version: 0.3.0
 Summary: Schema-driven REST API simulation with FastAPI, Pydantic, and Polyfactory
 Author: Semblance Contributors
 License-Expression: MIT
@@ -25,6 +25,7 @@ Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
 Requires-Dist: httpx>=0.25.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0.0; extra == "dev"
 Requires-Dist: ruff>=0.8.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
 Requires-Dist: bandit>=1.7.0; extra == "dev"
@@ -55,7 +56,7 @@ Define API behavior declaratively using schemas and dependency metadata—no end
 - **FastAPI-native** — Full OpenAPI, validation, async
 - **Deterministic** — Seeded generation for reproducible tests
 - **Extensible** — Custom link types via plugins
-- **Production-ready** — Error simulation, latency, pagination, stateful mode
+- **Production-ready** — Error simulation, latency, rate limiting, pagination, stateful mode, optional response validation
 
 ## Requirements
 
@@ -111,6 +112,8 @@ def users():
 app = api.as_fastapi()
 ```
 
+You can register PUT, PATCH, and DELETE endpoints the same way (`@api.put(...)`, `@api.patch(...)`, `@api.delete(..., output=None)` for 204).
+
 Run:
 
 ```bash
@@ -219,15 +222,18 @@ class User(BaseModel):
 
 | Feature | Description |
 |---------|-------------|
-| **SemblanceAPI** | GET and POST endpoints with input/output models |
+| **SemblanceAPI** | GET, POST, PUT, PATCH, DELETE endpoints with input/output models |
 | **Links** | FromInput, DateRangeFrom, WhenInput, ComputedFrom |
 | **Pagination** | PageParams, PaginatedResponse[T] |
 | **Seeding** | `SemblanceAPI(seed=42)` or `seed_from="seed"` |
 | **Error simulation** | `error_rate`, `error_codes` |
 | **Latency** | `latency_ms`, `jitter_ms` |
+| **Rate limiting** | `rate_limit=N` — 429 when exceeded (per endpoint, sliding window) |
 | **Filtering** | `filter_by` for list endpoints |
 | **Stateful mode** | `SemblanceAPI(stateful=True)` — POST stores, GET returns stored |
+| **Response validation** | `SemblanceAPI(validate_responses=True)` — verify output conforms to model |
 | **OpenAPI** | summary, description, tags on endpoints |
+| **Property-based testing** | `semblance.property_testing`: `strategy_for_input_model()`, `test_endpoint()` (Hypothesis) |
 
 ## Competitors & Alternatives
 
@@ -245,7 +251,7 @@ class User(BaseModel):
 | **Extensible (plugins)** | ✅ | <span title="Middleware-based; custom behavior via decorators or wrappers">🟡</span> | ❌ | ❌ | ✅ | <span title="Templates and response rules provide extensibility">🟡</span> |
 | **OpenAPI schema** | ✅ | ✅ | ✅ | ❌ | ✅ | <span title="Can import/export OpenAPI; design is GUI-first, not schema-first">🟡</span> |
 | **CI / pytest integration** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
-| **Property-based testing** | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
+| **Property-based testing** | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ |
 
 🟡 = partial or configurable
 

{semblance-0.2.2 → semblance-0.3.0}/README.md

@@ -16,7 +16,7 @@ Define API behavior declaratively using schemas and dependency metadata—no end
 - **FastAPI-native** — Full OpenAPI, validation, async
 - **Deterministic** — Seeded generation for reproducible tests
 - **Extensible** — Custom link types via plugins
-- **Production-ready** — Error simulation, latency, pagination, stateful mode
+- **Production-ready** — Error simulation, latency, rate limiting, pagination, stateful mode, optional response validation
 
 ## Requirements
 
@@ -72,6 +72,8 @@ def users():
 app = api.as_fastapi()
 ```
 
+You can register PUT, PATCH, and DELETE endpoints the same way (`@api.put(...)`, `@api.patch(...)`, `@api.delete(..., output=None)` for 204).
+
 Run:
 
 ```bash
@@ -180,15 +182,18 @@ class User(BaseModel):
 
 | Feature | Description |
 |---------|-------------|
-| **SemblanceAPI** | GET and POST endpoints with input/output models |
+| **SemblanceAPI** | GET, POST, PUT, PATCH, DELETE endpoints with input/output models |
 | **Links** | FromInput, DateRangeFrom, WhenInput, ComputedFrom |
 | **Pagination** | PageParams, PaginatedResponse[T] |
 | **Seeding** | `SemblanceAPI(seed=42)` or `seed_from="seed"` |
 | **Error simulation** | `error_rate`, `error_codes` |
 | **Latency** | `latency_ms`, `jitter_ms` |
+| **Rate limiting** | `rate_limit=N` — 429 when exceeded (per endpoint, sliding window) |
 | **Filtering** | `filter_by` for list endpoints |
 | **Stateful mode** | `SemblanceAPI(stateful=True)` — POST stores, GET returns stored |
+| **Response validation** | `SemblanceAPI(validate_responses=True)` — verify output conforms to model |
 | **OpenAPI** | summary, description, tags on endpoints |
+| **Property-based testing** | `semblance.property_testing`: `strategy_for_input_model()`, `test_endpoint()` (Hypothesis) |
 
 ## Competitors & Alternatives
 
@@ -206,7 +211,7 @@ class User(BaseModel):
 | **Extensible (plugins)** | ✅ | <span title="Middleware-based; custom behavior via decorators or wrappers">🟡</span> | ❌ | ❌ | ✅ | <span title="Templates and response rules provide extensibility">🟡</span> |
 | **OpenAPI schema** | ✅ | ✅ | ✅ | ❌ | ✅ | <span title="Can import/export OpenAPI; design is GUI-first, not schema-first">🟡</span> |
 | **CI / pytest integration** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
-| **Property-based testing** | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
+| **Property-based testing** | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ |
 
 🟡 = partial or configurable
 

{semblance-0.2.2 → semblance-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "semblance"
-version = "0.2.2"
+version = "0.3.0"
 description = "Schema-driven REST API simulation with FastAPI, Pydantic, and Polyfactory"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -35,6 +35,7 @@ dev = [
     "pytest>=7.0.0",
     "pytest-cov>=4.0.0",
     "httpx>=0.25.0",
+    "hypothesis>=6.0.0",
     "ruff>=0.8.0",
     "mypy>=1.0.0",
     "bandit>=1.7.0",
@@ -76,6 +77,10 @@ warn_unused_configs = true
 disallow_untyped_defs = false
 mypy_path = "src"
 
+[[tool.mypy.overrides]]
+module = ["semblance.*"]
+disallow_untyped_defs = true
+
 [[tool.mypy.overrides]]
 module = ["polyfactory.*"]
 ignore_missing_imports = true

{semblance-0.2.2 → semblance-0.3.0}/src/semblance/api.py

@@ -13,10 +13,12 @@ import re
 from collections.abc import Callable
 from typing import Annotated, Any, get_origin
 
-from fastapi import FastAPI, HTTPException, Query, Request
+from fastapi import Body, FastAPI, HTTPException, Query, Request
+from fastapi.responses import Response
 from pydantic import BaseModel
 
-from semblance.factory import build_response
+from semblance.factory import build_response, validate_response
+from semblance.rate_limit import get_limiter
 from semblance.state import StatefulStore
 
 
@@ -41,6 +43,7 @@ class EndpointSpec:
         "latency_ms",
         "jitter_ms",
         "filter_by",
+        "rate_limit",
         "summary",
         "description",
         "tags",
@@ -51,7 +54,7 @@ class EndpointSpec:
         path: str,
         methods: list[str],
         input_model: type[BaseModel],
-        output_annotation: type,
+        output_annotation: type | None,
         handler: Callable[..., Any],
         list_count: int | str = 5,
         seed_from: str | None = None,
@@ -60,6 +63,7 @@ class EndpointSpec:
         latency_ms: float = 0,
         jitter_ms: float = 0,
         filter_by: str | None = None,
+        rate_limit: float | None = None,
         summary: str | None = None,
         description: str | None = None,
         tags: list[str] | None = None,
@@ -76,6 +80,7 @@ class EndpointSpec:
         self.latency_ms = latency_ms
         self.jitter_ms = jitter_ms
         self.filter_by = filter_by
+        self.rate_limit = rate_limit
         self.summary = summary
         self.description = description
         self.tags = tags
@@ -90,12 +95,20 @@ class SemblanceAPI:
         seed: Optional seed for deterministic random generation.
         stateful: If True, POST responses are stored and GET list endpoints
             return stored instances instead of generating new ones.
+        validate_responses: If True, generated responses are validated against
+            the output model (for development/CI; adds overhead).
     """
 
-    def __init__(self, seed: int | None = None, stateful: bool = False) -> None:
+    def __init__(
+        self,
+        seed: int | None = None,
+        stateful: bool = False,
+        validate_responses: bool = False,
+    ) -> None:
         self._specs: list[EndpointSpec] = []
         self._seed = seed
         self._store: StatefulStore | None = StatefulStore() if stateful else None
+        self._validate_responses = validate_responses
 
     def clear_store(self, path: str | None = None) -> None:
         """Clear the stateful store. Only available when stateful=True."""
@@ -115,6 +128,7 @@ class SemblanceAPI:
         latency_ms: float = 0,
         jitter_ms: float = 0,
         filter_by: str | None = None,
+        rate_limit: float | None = None,
         summary: str | None = None,
         description: str | None = None,
         tags: list[str] | None = None,
@@ -140,6 +154,7 @@ class SemblanceAPI:
             latency_ms,
             jitter_ms,
             filter_by,
+            rate_limit,
             summary,
             description,
             tags,
@@ -158,6 +173,7 @@ class SemblanceAPI:
         latency_ms: float = 0,
         jitter_ms: float = 0,
         filter_by: str | None = None,
+        rate_limit: float | None = None,
         summary: str | None = None,
         description: str | None = None,
         tags: list[str] | None = None,
@@ -183,17 +199,147 @@ class SemblanceAPI:
             latency_ms,
             jitter_ms,
             filter_by,
+            rate_limit,
             summary,
             description,
             tags,
         )
 
+    def put(
+        self,
+        path: str,
+        *,
+        input: type[BaseModel],
+        output: type,
+        list_count: int | str = 5,
+        seed_from: str | None = None,
+        error_rate: float = 0,
+        error_codes: list[int] | None = None,
+        latency_ms: float = 0,
+        jitter_ms: float = 0,
+        filter_by: str | None = None,
+        rate_limit: float | None = None,
+        summary: str | None = None,
+        description: str | None = None,
+        tags: list[str] | None = None,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """
+        Register a PUT endpoint. Request body is validated against `input`.
+        Response is generated from `output` (single model or list[model]).
+
+        Usage:
+            @api.put("/users/{id}", input=UpdateUserRequest, output=User)
+            def update_user():
+                pass
+        """
+        return self._register(
+            path,
+            "PUT",
+            input,
+            output,
+            list_count,
+            seed_from,
+            error_rate,
+            error_codes,
+            latency_ms,
+            jitter_ms,
+            filter_by,
+            rate_limit,
+            summary,
+            description,
+            tags,
+        )
+
+    def patch(
+        self,
+        path: str,
+        *,
+        input: type[BaseModel],
+        output: type,
+        list_count: int | str = 5,
+        seed_from: str | None = None,
+        error_rate: float = 0,
+        error_codes: list[int] | None = None,
+        latency_ms: float = 0,
+        jitter_ms: float = 0,
+        filter_by: str | None = None,
+        rate_limit: float | None = None,
+        summary: str | None = None,
+        description: str | None = None,
+        tags: list[str] | None = None,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """
+        Register a PATCH endpoint. Request body is validated against `input`.
+        Response is generated from `output` (single model or list[model]).
+
+        Usage:
+            @api.patch("/users/{id}", input=PatchUserRequest, output=User)
+            def patch_user():
+                pass
+        """
+        return self._register(
+            path,
+            "PATCH",
+            input,
+            output,
+            list_count,
+            seed_from,
+            error_rate,
+            error_codes,
+            latency_ms,
+            jitter_ms,
+            filter_by,
+            rate_limit,
+            summary,
+            description,
+            tags,
+        )
+
+    def delete(
+        self,
+        path: str,
+        *,
+        input: type[BaseModel],
+        output: type | None = None,
+        rate_limit: float | None = None,
+        summary: str | None = None,
+        description: str | None = None,
+        tags: list[str] | None = None,
+    ) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+        """
+        Register a DELETE endpoint. Path params (and optional body) are validated
+        against `input`. If `output` is None, returns 204 No Content.
+        If `output` is a model, returns 200 with generated body.
+
+        Usage:
+            @api.delete("/users/{id}", input=DeleteUserQuery)
+            def delete_user():
+                pass
+        """
+        return self._register(
+            path,
+            "DELETE",
+            input,
+            output,
+            list_count=1,
+            seed_from=None,
+            error_rate=0,
+            error_codes=None,
+            latency_ms=0,
+            jitter_ms=0,
+            filter_by=None,
+            rate_limit=rate_limit,
+            summary=summary,
+            description=description,
+            tags=tags,
+        )
+
     def _register(
         self,
         path: str,
         method: str,
         input_model: type[BaseModel],
-        output: type,
+        output: type | None,
         list_count: int | str = 5,
         seed_from: str | None = None,
         error_rate: float = 0,
@@ -201,6 +347,7 @@ class SemblanceAPI:
         latency_ms: float = 0,
         jitter_ms: float = 0,
         filter_by: str | None = None,
+        rate_limit: float | None = None,
         summary: str | None = None,
         description: str | None = None,
         tags: list[str] | None = None,
@@ -220,6 +367,7 @@ class SemblanceAPI:
                     latency_ms=latency_ms,
                     jitter_ms=jitter_ms,
                     filter_by=filter_by,
+                    rate_limit=rate_limit,
                     summary=summary,
                     description=description,
                     tags=tags,
@@ -246,6 +394,12 @@ class SemblanceAPI:
                     self._register_get(app, spec)
                 elif method == "POST":
                     self._register_post(app, spec)
+                elif method == "PUT":
+                    self._register_put(app, spec)
+                elif method == "PATCH":
+                    self._register_patch(app, spec)
+                elif method == "DELETE":
+                    self._register_delete(app, spec)
 
         return app
 
@@ -307,6 +461,17 @@ class SemblanceAPI:
         merged = {**data.model_dump(), **path_params}
         return input_model.model_validate(merged)
 
+    def _check_rate_limit(self, spec: EndpointSpec) -> None:
+        """Raise HTTPException 429 if rate limit exceeded."""
+        if spec.rate_limit is None or spec.rate_limit <= 0:
+            return
+        limiter = get_limiter()
+        method = spec.methods[0]
+        if not limiter.check_and_record(spec.path, method, spec.rate_limit):
+            raise HTTPException(
+                status_code=429, detail="Rate limit exceeded (simulated)"
+            )
+
     def _register_get(self, app: FastAPI, spec: EndpointSpec) -> None:
         input_model = spec.input_model
         output_annotation = spec.output_annotation
@@ -324,16 +489,67 @@ class SemblanceAPI:
             request: Request,
             query: Annotated[input_model, Query()],
         ) -> output_annotation:
+            assert output_annotation is not None
+            self._check_rate_limit(spec)
             merged = self._merge_path_params(
                 input_model, query, dict(request.path_params)
             )
             seed = self._resolve_seed(seed_from, merged)
             self._maybe_raise_error(error_rate, error_codes, seed)
             await self._await_latency(latency_ms, jitter_ms)
+            response: BaseModel | list[BaseModel]
             if store is not None and get_origin(output_annotation) is list:
-                return store.get_all(path)
+                response = store.get_all(path)
+            else:
+                count = self._resolve_list_count(list_count, merged)
+                response = build_response(
+                    output_annotation,
+                    input_model,
+                    merged,
+                    list_count=count,
+                    seed=seed,
+                    filter_by=filter_by,
+                )
+            if self._validate_responses:
+                validate_response(output_annotation, response)
+            return response
+
+        kwargs: dict[str, Any] = {"response_model": output_annotation}
+        if spec.summary is not None:
+            kwargs["summary"] = spec.summary
+        if spec.description is not None:
+            kwargs["description"] = spec.description
+        if spec.tags is not None:
+            kwargs["tags"] = spec.tags
+        app.get(spec.path, **kwargs)(handler)
+
+    def _register_post(self, app: FastAPI, spec: EndpointSpec) -> None:
+        assert spec.output_annotation is not None
+        input_model = spec.input_model
+        output_annotation = spec.output_annotation
+        list_count = spec.list_count
+        seed_from = spec.seed_from
+        error_rate = spec.error_rate
+        error_codes = spec.error_codes
+        latency_ms = spec.latency_ms
+        jitter_ms = spec.jitter_ms
+        filter_by = spec.filter_by
+        store = self._store
+        path = spec.path
+
+        async def handler(
+            request: Request,
+            body: input_model,
+        ) -> output_annotation:
+            self._check_rate_limit(spec)
+            merged = self._merge_path_params(
+                input_model, body, dict(request.path_params)
+            )
+            seed = self._resolve_seed(seed_from, merged)
+            self._maybe_raise_error(error_rate, error_codes, seed)
+            await self._await_latency(latency_ms, jitter_ms)
             count = self._resolve_list_count(list_count, merged)
-            return build_response(
+            response = build_response(
                 output_annotation,
                 input_model,
                 merged,
@@ -341,6 +557,11 @@ class SemblanceAPI:
                 seed=seed,
                 filter_by=filter_by,
             )
+            if store is not None and not isinstance(response, list):
+                response = store.add(path, response)
+            if self._validate_responses:
+                validate_response(output_annotation, response)
+            return response
 
         kwargs: dict[str, Any] = {"response_model": output_annotation}
         if spec.summary is not None:
@@ -349,9 +570,10 @@ class SemblanceAPI:
             kwargs["description"] = spec.description
         if spec.tags is not None:
             kwargs["tags"] = spec.tags
-        app.get(spec.path, **kwargs)(handler)
+        app.post(spec.path, **kwargs)(handler)
 
-    def _register_post(self, app: FastAPI, spec: EndpointSpec) -> None:
+    def _register_put(self, app: FastAPI, spec: EndpointSpec) -> None:
+        assert spec.output_annotation is not None
         input_model = spec.input_model
         output_annotation = spec.output_annotation
         list_count = spec.list_count
@@ -361,13 +583,12 @@ class SemblanceAPI:
         latency_ms = spec.latency_ms
         jitter_ms = spec.jitter_ms
         filter_by = spec.filter_by
-        store = self._store
-        path = spec.path
 
         async def handler(
             request: Request,
             body: input_model,
         ) -> output_annotation:
+            self._check_rate_limit(spec)
             merged = self._merge_path_params(
                 input_model, body, dict(request.path_params)
             )
@@ -383,8 +604,8 @@ class SemblanceAPI:
                 seed=seed,
                 filter_by=filter_by,
             )
-            if store is not None and not isinstance(response, list):
-                response = store.add(path, response)
+            if self._validate_responses:
+                validate_response(output_annotation, response)
             return response
 
         kwargs: dict[str, Any] = {"response_model": output_annotation}
@@ -394,4 +615,94 @@ class SemblanceAPI:
             kwargs["description"] = spec.description
         if spec.tags is not None:
             kwargs["tags"] = spec.tags
-        app.post(spec.path, **kwargs)(handler)
+        app.put(spec.path, **kwargs)(handler)
+
+    def _register_patch(self, app: FastAPI, spec: EndpointSpec) -> None:
+        assert spec.output_annotation is not None
+        input_model = spec.input_model
+        output_annotation = spec.output_annotation
+        list_count = spec.list_count
+        seed_from = spec.seed_from
+        error_rate = spec.error_rate
+        error_codes = spec.error_codes
+        latency_ms = spec.latency_ms
+        jitter_ms = spec.jitter_ms
+        filter_by = spec.filter_by
+
+        async def handler(
+            request: Request,
+            body: input_model,
+        ) -> output_annotation:
+            self._check_rate_limit(spec)
+            merged = self._merge_path_params(
+                input_model, body, dict(request.path_params)
+            )
+            seed = self._resolve_seed(seed_from, merged)
+            self._maybe_raise_error(error_rate, error_codes, seed)
+            await self._await_latency(latency_ms, jitter_ms)
+            count = self._resolve_list_count(list_count, merged)
+            response = build_response(
+                output_annotation,
+                input_model,
+                merged,
+                list_count=count,
+                seed=seed,
+                filter_by=filter_by,
+            )
+            if self._validate_responses:
+                validate_response(output_annotation, response)
+            return response
+
+        kwargs: dict[str, Any] = {"response_model": output_annotation}
+        if spec.summary is not None:
+            kwargs["summary"] = spec.summary
+        if spec.description is not None:
+            kwargs["description"] = spec.description
+        if spec.tags is not None:
+            kwargs["tags"] = spec.tags
+        app.patch(spec.path, **kwargs)(handler)
+
+    def _register_delete(self, app: FastAPI, spec: EndpointSpec) -> None:
+        input_model = spec.input_model
+        output_annotation = spec.output_annotation
+        seed_from = spec.seed_from
+        error_rate = spec.error_rate
+        error_codes = spec.error_codes
+        latency_ms = spec.latency_ms
+        jitter_ms = spec.jitter_ms
+
+        async def handler(
+            request: Request,
+            body: input_model | None = Body(None),
+        ) -> Any:
+            self._check_rate_limit(spec)
+            path_params = dict(request.path_params)
+            data: dict[str, Any] = body.model_dump() if body is not None else {}
+            merged = input_model.model_validate({**data, **path_params})
+            seed = self._resolve_seed(seed_from, merged)
+            self._maybe_raise_error(error_rate, error_codes, seed)
+            await self._await_latency(latency_ms, jitter_ms)
+            if output_annotation is None:
+                return Response(status_code=204)
+            response = build_response(
+                output_annotation,
+                input_model,
+                merged,
+                list_count=1,
+                seed=seed,
+                filter_by=None,
+            )
+            if self._validate_responses:
+                validate_response(output_annotation, response)
+            return response
+
+        kwargs: dict[str, Any] = {}
+        if output_annotation is not None:
+            kwargs["response_model"] = output_annotation
+        if spec.summary is not None:
+            kwargs["summary"] = spec.summary
+        if spec.description is not None:
+            kwargs["description"] = spec.description
+        if spec.tags is not None:
+            kwargs["tags"] = spec.tags
+        app.delete(spec.path, **kwargs)(handler)

{semblance-0.2.2 → semblance-0.3.0}/src/semblance/cli.py

@@ -9,9 +9,10 @@ import argparse
 import importlib.util
 import sys
 from pathlib import Path
+from typing import Any
 
 
-def _load_app(path: str):
+def _load_app(path: str) -> Any:
     """Load app from module:attr. If attr has as_fastapi(), it is called to get FastAPI app."""
     if ":" not in path:
         raise SystemExit(

{semblance-0.2.2 → semblance-0.3.0}/src/semblance/export.py

@@ -16,7 +16,7 @@ from fastapi.testclient import TestClient
 
 def _get_routes(app: FastAPI) -> list[tuple[str, str, str]]:
     """Return (path, method, route_id) for each API route."""
-    routes = []
+    routes: list[tuple[str, str, str]] = []
     for route in app.routes:
         if hasattr(route, "path") and hasattr(route, "methods"):
             for method in route.methods - {"HEAD", "OPTIONS"}:

{semblance-0.2.2 → semblance-0.3.0}/src/semblance/factory.py

@@ -187,3 +187,18 @@ def build_response(
             "Use a Pydantic BaseModel or list[SomeModel] for output."
         )
     return build_one(model, input_model, input_instance, seed=seed)
+
+
+def validate_response(
+    output_annotation: type,
+    instance: BaseModel | list[BaseModel],
+) -> None:
+    """
+    Validate that instance conforms to output_annotation.
+    Raises ValidationError on mismatch. For list/PaginatedResponse,
+    validates the structure and each item.
+    """
+    from pydantic import TypeAdapter
+
+    adapter: TypeAdapter[Any] = TypeAdapter(output_annotation)
+    adapter.validate_python(instance)

semblance-0.3.0/src/semblance/property_testing.py

@@ -0,0 +1,140 @@
+"""
+Property-based testing helpers for Semblance APIs.
+
+Generate Hypothesis strategies from input models and run endpoint tests
+that validate responses against output schemas and optional invariants.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from typing import Annotated, Any, get_args, get_origin
+
+from pydantic import BaseModel
+
+try:
+    from hypothesis import given
+    from hypothesis import strategies as st
+except ImportError as e:
+    raise ImportError(
+        "Property-based testing requires hypothesis. Install with: pip install semblance[dev]"
+    ) from e
+
+
+def _parse_path_params(path: str) -> list[str]:
+    """Extract path param names from template, e.g. '/users/{id}' -> ['id']."""
+    return re.findall(r"\{(\w+)\}", path)
+
+
+def _get_bare_annotation(annotation: type) -> type:
+    """Strip Annotated and Union to get a concrete type for strategy generation."""
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+    if origin is Annotated and args:
+        return _get_bare_annotation(args[0])
+    if origin is type(None) or (origin is not None and "Union" in str(origin)) and args:
+        for a in args:
+            if a is type(None):
+                continue
+            return _get_bare_annotation(a)
+    return annotation
+
+
+def _strategy_for_annotation(annotation: type) -> st.SearchStrategy[Any]:
+    """Build a Hypothesis strategy for a single field annotation."""
+    bare = _get_bare_annotation(annotation)
+    if bare is type(None):
+        return st.none()
+    try:
+        if isinstance(bare, type) and issubclass(bare, BaseModel):
+            return strategy_for_input_model(bare)
+    except TypeError:
+        pass
+    if bare is str:
+        return st.text()
+    if bare is int:
+        return st.integers()
+    if bare is float:
+        return st.floats(allow_nan=False)
+    if bare is bool:
+        return st.booleans()
+    try:
+        return st.from_type(bare)
+    except Exception:
+        return st.none()
+
+
+def strategy_for_input_model(
+    model: type[BaseModel],
+    path_template: str | None = None,
+) -> st.SearchStrategy[BaseModel]:
+    """
+    Build a Hypothesis strategy that generates instances of the input model.
+
+    Use for GET (query) or POST/PUT/PATCH (body) input. If path_template is
+    given (e.g. '/users/{id}'), path param names are inferred; the strategy
+    still generates full model instances (path params can be passed separately
+    when building the request).
+    """
+    strategies: dict[str, st.SearchStrategy[Any]] = {}
+    for name, field in model.model_fields.items():
+        ann = field.annotation
+        if ann is not None:
+            strategies[name] = _strategy_for_annotation(ann)
+        else:
+            strategies[name] = st.none()
+    return st.builds(model, **strategies)
+
+
+def test_endpoint(
+    client: Any,
+    method: str,
+    path: str,
+    input_strategy: st.SearchStrategy[BaseModel],
+    output_model: type,
+    path_params: dict[str, Any] | None = None,
+    validate_response: bool = True,
+    invariants: tuple[Callable[[Any, Any], bool], ...] = (),
+) -> None:
+    """
+    Run a property-based test: draw input from input_strategy, call the
+    endpoint, assert status and that response conforms to output_model.
+    Optional invariants are (input, output) -> bool; all must hold.
+    """
+    path_params = path_params or {}
+    path_params_from_template = {
+        k: (path_params.get(k) or "placeholder") for k in _parse_path_params(path)
+    }
+
+    @given(input_strategy)
+    def _run(input_instance: BaseModel) -> None:
+        data = input_instance.model_dump()
+        url = path
+        for key, val in path_params_from_template.items():
+            url = url.replace("{" + key + "}", str(val))
+        if method.upper() == "GET":
+            from urllib.parse import urlencode
+
+            query = urlencode(data)
+            url = f"{url}?{query}" if query else url
+            r = client.get(url)
+        elif method.upper() in ("POST", "PUT", "PATCH"):
+            r = client.request(method.upper(), url, json=data)
+        elif method.upper() == "DELETE":
+            r = client.delete(url)
+        else:
+            raise ValueError(f"Unsupported method {method}")
+        assert r.status_code in (200, 201, 204), (r.status_code, r.text)
+        if r.status_code == 204:
+            return
+        body = r.json()
+        if validate_response:
+            from pydantic import TypeAdapter
+
+            adapter: TypeAdapter[Any] = TypeAdapter(output_model)
+            adapter.validate_python(body)
+        for inv in invariants:
+            assert inv(input_instance, body), f"Invariant failed: {inv}"
+
+    _run()

semblance-0.3.0/src/semblance/rate_limit.py

@@ -0,0 +1,48 @@
+"""
+Rate limiting simulation for endpoints.
+
+Sliding-window: at most N requests per second per (path, method).
+Per-process, in-memory; for simulation only.
+"""
+
+import time
+from collections import defaultdict
+from threading import Lock
+
+
+class RateLimiter:
+    """Sliding-window rate limiter keyed by (path, method)."""
+
+    def __init__(self) -> None:
+        self._timestamps: dict[tuple[str, str], list[float]] = defaultdict(list)
+        self._lock = Lock()
+
+    def check_and_record(self, path: str, method: str, limit: float) -> bool:
+        """
+        Record a request and return True if under limit, False if over limit.
+
+        Uses a 1-second sliding window: requests older than 1 second are dropped.
+        """
+        if limit <= 0:
+            return True
+        now = time.monotonic()
+        key = (path, method)
+        with self._lock:
+            ts_list = self._timestamps[key]
+            # Drop timestamps older than 1 second
+            ts_list[:] = [t for t in ts_list if now - t < 1.0]
+            if len(ts_list) >= limit:
+                return False
+            ts_list.append(now)
+        return True
+
+
+_limiter: RateLimiter | None = None
+
+
+def get_limiter() -> RateLimiter:
+    """Return the global rate limiter instance."""
+    global _limiter
+    if _limiter is None:
+        _limiter = RateLimiter()
+    return _limiter

{semblance-0.2.2 → semblance-0.3.0/src/semblance.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: semblance
-Version: 0.2.2
+Version: 0.3.0
 Summary: Schema-driven REST API simulation with FastAPI, Pydantic, and Polyfactory
 Author: Semblance Contributors
 License-Expression: MIT
@@ -25,6 +25,7 @@ Provides-Extra: dev
 Requires-Dist: pytest>=7.0.0; extra == "dev"
 Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
 Requires-Dist: httpx>=0.25.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0.0; extra == "dev"
 Requires-Dist: ruff>=0.8.0; extra == "dev"
 Requires-Dist: mypy>=1.0.0; extra == "dev"
 Requires-Dist: bandit>=1.7.0; extra == "dev"
@@ -55,7 +56,7 @@ Define API behavior declaratively using schemas and dependency metadata—no end
 - **FastAPI-native** — Full OpenAPI, validation, async
 - **Deterministic** — Seeded generation for reproducible tests
 - **Extensible** — Custom link types via plugins
-- **Production-ready** — Error simulation, latency, pagination, stateful mode
+- **Production-ready** — Error simulation, latency, rate limiting, pagination, stateful mode, optional response validation
 
 ## Requirements
 
@@ -111,6 +112,8 @@ def users():
 app = api.as_fastapi()
 ```
 
+You can register PUT, PATCH, and DELETE endpoints the same way (`@api.put(...)`, `@api.patch(...)`, `@api.delete(..., output=None)` for 204).
+
 Run:
 
 ```bash
@@ -219,15 +222,18 @@ class User(BaseModel):
 
 | Feature | Description |
 |---------|-------------|
-| **SemblanceAPI** | GET and POST endpoints with input/output models |
+| **SemblanceAPI** | GET, POST, PUT, PATCH, DELETE endpoints with input/output models |
 | **Links** | FromInput, DateRangeFrom, WhenInput, ComputedFrom |
 | **Pagination** | PageParams, PaginatedResponse[T] |
 | **Seeding** | `SemblanceAPI(seed=42)` or `seed_from="seed"` |
 | **Error simulation** | `error_rate`, `error_codes` |
 | **Latency** | `latency_ms`, `jitter_ms` |
+| **Rate limiting** | `rate_limit=N` — 429 when exceeded (per endpoint, sliding window) |
 | **Filtering** | `filter_by` for list endpoints |
 | **Stateful mode** | `SemblanceAPI(stateful=True)` — POST stores, GET returns stored |
+| **Response validation** | `SemblanceAPI(validate_responses=True)` — verify output conforms to model |
 | **OpenAPI** | summary, description, tags on endpoints |
+| **Property-based testing** | `semblance.property_testing`: `strategy_for_input_model()`, `test_endpoint()` (Hypothesis) |
 
 ## Competitors & Alternatives
 
@@ -245,7 +251,7 @@ class User(BaseModel):
 | **Extensible (plugins)** | ✅ | <span title="Middleware-based; custom behavior via decorators or wrappers">🟡</span> | ❌ | ❌ | ✅ | <span title="Templates and response rules provide extensibility">🟡</span> |
 | **OpenAPI schema** | ✅ | ✅ | ✅ | ❌ | ✅ | <span title="Can import/export OpenAPI; design is GUI-first, not schema-first">🟡</span> |
 | **CI / pytest integration** | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
-| **Property-based testing** | ❌ | ❌ | ❌ | ❌ | ✅ | ❌ |
+| **Property-based testing** | ✅ | ❌ | ❌ | ❌ | ✅ | ❌ |
 
 🟡 = partial or configurable
 

{semblance-0.2.2 → semblance-0.3.0}/src/semblance.egg-info/SOURCES.txt

@@ -9,6 +9,8 @@ src/semblance/factory.py
 src/semblance/links.py
 src/semblance/pagination.py
 src/semblance/plugins.py
+src/semblance/property_testing.py
+src/semblance/rate_limit.py
 src/semblance/resolver.py
 src/semblance/state.py
 src/semblance/testing.py
@@ -26,6 +28,7 @@ tests/test_links.py
 tests/test_phase2.py
 tests/test_phase3.py
 tests/test_phase4.py
+tests/test_phase5.py
 tests/test_plugins.py
 tests/test_resolver.py
 tests/test_state.py

{semblance-0.2.2 → semblance-0.3.0}/src/semblance.egg-info/requires.txt

@@ -7,6 +7,7 @@ uvicorn>=0.30.0
 pytest>=7.0.0
 pytest-cov>=4.0.0
 httpx>=0.25.0
+hypothesis>=6.0.0
 ruff>=0.8.0
 mypy>=1.0.0
 bandit>=1.7.0

semblance-0.3.0/tests/test_phase5.py

@@ -0,0 +1,164 @@
+"""Tests for Phase 5: PUT/PATCH/DELETE, rate limiting, response validation, property-based testing."""
+
+import time
+
+import pytest
+from pydantic import BaseModel
+
+from semblance import SemblanceAPI
+from semblance.testing import test_client as make_client
+from tests.example_models import User, UserQuery
+
+
+class UpdateBody(BaseModel):
+    """Minimal body for PUT/PATCH."""
+
+    name: str = "updated"
+
+
+class DeletePathInput(BaseModel):
+    """Path-only input for DELETE (e.g. id from path)."""
+
+    id: str = ""
+
+
+# --- PUT / PATCH / DELETE ---
+
+
+class TestPutPatchDelete:
+    def test_put_returns_generated_response(self):
+        api = SemblanceAPI(seed=42)
+        api.put("/users/{id}", input=UpdateBody, output=User)(lambda: None)
+        app = api.as_fastapi()
+        client = make_client(app)
+        r = client.put("/users/abc", json={"name": "put-user"})
+        assert r.status_code == 200
+        data = r.json()
+        assert "name" in data
+        assert data["name"] == "put-user"
+
+    def test_patch_returns_generated_response(self):
+        api = SemblanceAPI(seed=42)
+        api.patch("/users/{id}", input=UpdateBody, output=User)(lambda: None)
+        app = api.as_fastapi()
+        client = make_client(app)
+        r = client.patch("/users/xyz", json={"name": "patch-user"})
+        assert r.status_code == 200
+        data = r.json()
+        assert data["name"] == "patch-user"
+
+    def test_delete_204_when_no_output(self):
+        api = SemblanceAPI()
+        api.delete("/users/{id}", input=DeletePathInput)(lambda: None)
+        app = api.as_fastapi()
+        client = make_client(app)
+        r = client.delete("/users/123")
+        assert r.status_code == 204
+        assert r.content in (b"", b" ")
+
+    def test_delete_200_with_output_model(self):
+        api = SemblanceAPI(seed=42)
+        api.delete("/users/{id}", input=DeletePathInput, output=User)(lambda: None)
+        app = api.as_fastapi()
+        client = make_client(app)
+        r = client.delete("/users/123")
+        assert r.status_code == 200
+        data = r.json()
+        assert "name" in data
+
+
+# --- Rate limiting ---
+
+
+class TestRateLimit:
+    def test_rate_limit_returns_429_when_exceeded(self):
+        api = SemblanceAPI()
+        api.get(
+            "/limited",
+            input=UserQuery,
+            output=list[User],
+            rate_limit=2,
+        )(lambda: None)
+        app = api.as_fastapi()
+        client = make_client(app)
+        r1 = client.get("/limited?name=a")
+        r2 = client.get("/limited?name=b")
+        r3 = client.get("/limited?name=c")
+        assert r1.status_code == 200
+        assert r2.status_code == 200
+        assert r3.status_code == 429
+
+    def test_rate_limit_allows_after_window(self):
+        api = SemblanceAPI()
+        api.get(
+            "/limited2",
+            input=UserQuery,
+            output=list[User],
+            rate_limit=1,
+        )(lambda: None)
+        app = api.as_fastapi()
+        client = make_client(app)
+        assert client.get("/limited2?name=a").status_code == 200
+        assert client.get("/limited2?name=b").status_code == 429
+        time.sleep(1.1)
+        assert client.get("/limited2?name=c").status_code == 200
+
+
+# --- Response validation ---
+
+
+class TestValidateResponses:
+    def test_validate_responses_does_not_raise_on_valid_response(self):
+        api = SemblanceAPI(validate_responses=True)
+        api.get("/users", input=UserQuery, output=list[User])(lambda: None)
+        app = api.as_fastapi()
+        client = make_client(app)
+        r = client.get("/users?name=alice")
+        assert r.status_code == 200
+        assert isinstance(r.json(), list)
+
+
+# --- Property-based testing ---
+
+
+@pytest.mark.skipif(
+    __import__("importlib.util").util.find_spec("hypothesis") is None,
+    reason="hypothesis not installed",
+)
+class TestPropertyBased:
+    def test_strategy_for_input_model_generates_valid_instances(self):
+        from hypothesis import given
+
+        from semblance.property_testing import strategy_for_input_model
+
+        strategy = strategy_for_input_model(UserQuery)
+
+        @given(strategy)
+        def run(inp):
+            assert isinstance(inp, UserQuery)
+            parsed = UserQuery.model_validate(inp.model_dump())
+            assert parsed.name == inp.name
+
+        run()
+
+    def test_test_endpoint_get_validates_responses(self):
+        from hypothesis import given
+        from pydantic import TypeAdapter
+
+        from semblance.property_testing import strategy_for_input_model
+
+        api = SemblanceAPI(seed=42)
+        api.get("/users", input=UserQuery, output=list[User], list_count=2)(
+            lambda: None
+        )
+        app = api.as_fastapi()
+        client = make_client(app)
+        strategy = strategy_for_input_model(UserQuery)
+
+        @given(strategy)
+        def run(inp):
+            r = client.get("/users", params=inp.model_dump())
+            assert r.status_code == 200
+            TypeAdapter(list[User]).validate_python(r.json())
+
+        run()