modmex-lambda 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

modmex_lambda/event_handler/routing.py

@@ -190,8 +190,50 @@ class HasRoutes(ABC):
             cache_control=cache_control,
         )
 
+    def options(
+        self,
+        rule: str,
+        description: str | None = None,
+        status_code: int = DEFAULT_STATUS_CODE,
+        middlewares: list[AnyCallableT] | None = None,
+        cors: bool | None = None,
+        compress: bool = False,
+        cache_control: str | None = None,
+    ) -> Callable[[AnyCallableT], AnyCallableT]:
+        return self.route(
+            rule=rule,
+            method="OPTIONS",
+            description=description,
+            status_code=status_code,
+            middlewares=middlewares,
+            cors=cors,
+            compress=compress,
+            cache_control=cache_control,
+        )
+
+    def any(
+        self,
+        rule: str,
+        description: str | None = None,
+        status_code: int = DEFAULT_STATUS_CODE,
+        middlewares: list[AnyCallableT] | None = None,
+        cors: bool | None = None,
+        compress: bool = False,
+        cache_control: str | None = None,
+    ) -> Callable[[AnyCallableT], AnyCallableT]:
+        return self.route(
+            rule=rule,
+            method="ANY",
+            description=description,
+            status_code=status_code,
+            middlewares=middlewares,
+            cors=cors,
+            compress=compress,
+            cache_control=cache_control,
+        )
+
 
-class IRouter(ABC):
+class IRouter(HasRoutes, ABC):
     _routes: list[IRoute]
 
     @abstractmethod

{modmex_lambda-0.2.0.dist-info → modmex_lambda-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: modmex-lambda
-Version: 0.2.0
+Version: 0.3.0
 Summary: Ultra-lightweight AWS Lambda utilities for API Gateway routing and event handling.
 Author: Modmex
 License: MIT
@@ -60,7 +60,9 @@ def ping():
     return {"message": "pong"}
 
 
-handler = app.handler
+def handler(event, context):
+    return app.resolve(event, context)
+
 ```
 
 The internal base resolver is intentionally not exported from the package root;
@@ -84,6 +86,25 @@ def create_user():
 Supported route decorators include `get`, `post`, `put`, `patch`, `delete`,
 `options`, and `any`.
 
+You can also declare routes on a standalone router and include it in the
+resolver:
+
+```python
+from modmex_lambda import ApiGatewayHttpResolver
+from modmex_lambda.routing import Router
+
+app = ApiGatewayHttpResolver()
+router = Router()
+
+
+@router.get("/health")
+def health():
+    return {"ok": True}
+
+
+app.include_router(router)
+```
+
 Routers can also strip deployment prefixes:
 
 ```python
@@ -161,6 +182,38 @@ Route return values are converted to API Gateway proxy responses:
 - `(body, status_code)` sets the response status.
 - `Response` gives full control over status, headers, cookies, and content type.
 
+Use plain return values for simple JSON endpoints:
+
+```python
+from modmex import BaseModel
+
+
+class User(BaseModel):
+    id: int
+    name: str
+
+
+@app.get("/users/<user_id>")
+def get_user(user_id: int):
+    user = User(id=user_id, name="Ada")
+    return user.model_dump()
+
+
+@app.post("/users", status_code=201)
+def create_user():
+    user = User(id=42, name="Ada")
+    return user.model_dump()
+
+
+@app.delete("/users/<user_id>")
+def delete_user(user_id: int):
+    return {"deleted": user_id}, 202
+```
+
+Use `Response` when the endpoint needs explicit response metadata. If you are
+returning the same `User` model, pass `user.model_dump_json()` as the body and
+set `content_type="application/json"`:
+
 ```python
 from modmex_lambda import Response
 from modmex_lambda.shared.cookies import Cookie
@@ -168,13 +221,63 @@ from modmex_lambda.shared.cookies import Cookie
 
 @app.get("/session")
 def session():
+    user = User(id=42, name="Ada")
     return Response(
         status_code=200,
-        body={"ok": True},
-        cookies=[Cookie("seen", "true", secure=True)],
+        content_type="application/json",
+        body=user.model_dump_json(),
+        headers={"x-app": "users"},
+        cookies=[
+            Cookie(
+                "session",
+                "abc",
+                path="/",
+                http_only=True,
+                secure=True,
+                max_age=3600,
+            ),
+        ],
     )
 ```
 
+`Response` accepts:
+
+- `status_code`: the HTTP status code returned to API Gateway.
+- `body`: a JSON-serializable object, `str`, `bytes`, or `None`.
+- `content_type`: sets `Content-Type` unless the header is already present.
+- `headers`: a mapping of header names to a string or list of strings.
+- `cookies`: a list of `Cookie` objects.
+- `compress`: overrides route-level gzip compression for that response.
+
+When `Content-Type` starts with `application/json`, non-string bodies are
+serialized with the app serializer. Binary bodies are base64 encoded.
+
+For `modmex` models, prefer `model_dump()` when returning plain JSON objects.
+Use `model_dump_json()` when you already need to build a `Response` and want to
+send the serialized JSON string directly with `content_type="application/json"`.
+
+```python
+@app.get("/avatar/<user_id>")
+def avatar(user_id: int):
+    image_bytes = load_avatar(user_id)
+    return Response(
+        status_code=200,
+        content_type="image/png",
+        body=image_bytes,
+        headers={"Cache-Control": "max-age=3600"},
+    )
+```
+
+Route options can add response behavior without constructing `Response` in every
+handler:
+
+```python
+@app.get("/report", cache_control="max-age=60", compress=True)
+def report():
+    return {"items": build_report()}
+```
+
+Compression is applied only when the request includes `Accept-Encoding: gzip`.
 REST API responses use `multiValueHeaders`; HTTP API responses use the v2
 `headers` and `cookies` shape.
 
@@ -407,8 +510,69 @@ def lambda_handler(event: APIGatewayHttpEvent, context):
 
 ## Validation
 
-Modmex is the default validation and coercion engine. Pydantic is not required
-for normal operation.
+Modmex is the default validation and coercion engine. It is used for path,
+query, header, cookie, and body parameters declared with `Annotated`, and it is
+paired with the default JSON serializer for common values like enums, dates,
+datetimes, decimals, and dataclasses.
+
+```python
+from datetime import date
+from decimal import Decimal
+from enum import Enum
+from typing import Annotated
+
+from modmex import BaseModel
+from modmex_lambda import ApiGatewayHttpResolver
+from modmex_lambda.event_handler.params import Body, Path, Query
+
+app = ApiGatewayHttpResolver()
+
+
+class Plan(str, Enum):
+    FREE = "free"
+    PRO = "pro"
+
+
+class CreateAccount(BaseModel):
+    name: str
+    plan: Plan = Plan.FREE
+    trial_ends_on: date | None = None
+
+
+class Account(BaseModel):
+    id: int
+    name: str
+    plan: Plan
+    balance: Decimal
+
+
+@app.post("/accounts", status_code=201)
+def create_account(payload: Annotated[CreateAccount, Body()]):
+    account = Account(
+        id=42,
+        name=payload.name,
+        plan=payload.plan,
+        balance=Decimal("0.00"),
+    )
+    # Return model_dump() when you want the response body to be a JSON object.
+    return account.model_dump()
+
+
+@app.get("/accounts/<account_id>")
+def get_account(
+    account_id: Annotated[int, Path()],
+    include_usage: Annotated[bool, Query()] = False,
+):
+    return {
+        "id": account_id,
+        "include_usage": include_usage,
+        "created_on": date(2026, 1, 1),
+    }
+```
+
+If validation fails, the resolver returns `400` with a compact validation error
+payload. For domain-specific errors, register an exception handler and return a
+`Response` with the shape your API expects.
 
 ## Logging
 
@@ -426,18 +590,6 @@ def lambda_handler(event, context):
 The logger emits structured JSON and can extract Lambda request IDs and API
 Gateway correlation IDs.
 
-## Benchmarks
-
-The benchmark suite lives in `.benchmark/api_gateway_benchmark.py`.
-
-It covers cold imports, app setup, route registration, API Gateway v1/v2
-invocation, `event_parser`, `event_source`, and logger hot paths.
-
-```bash
-poetry run python .benchmark/api_gateway_benchmark.py
-```
-
-More details are in `.benchmark/README.md`.
 
 ## Limitations
 

{modmex_lambda-0.2.0.dist-info → modmex_lambda-0.3.0.dist-info}/RECORD

@@ -27,7 +27,7 @@ modmex_lambda/event_handler/middlewares.py,sha256=oOsQ0nOl7lc_N-kt8wTx7qOXNE5VtR
 modmex_lambda/event_handler/params.py,sha256=nNhLKduyeQ6TI9Zli32_XtRM93e973igOOZSY0vcpy4,544
 modmex_lambda/event_handler/request.py,sha256=f5TMv6muYfYOsLbZMPdd6kRMza8U2-UiyNmvuB5grH4,1705
 modmex_lambda/event_handler/response.py,sha256=izW9v_0E91UsQKX6-W26wnuAy-YP2_kTPbA5OW9L3tM,1988
-modmex_lambda/event_handler/routing.py,sha256=MqwHvf9d4qu_1U-qxx85q5m22BQ3kAzfhPeJeMUyaTs,16146
+modmex_lambda/event_handler/routing.py,sha256=ei2cZNwf850cPrOwMt-_LEoP9VEH6bSDpll5SgtVve8,17443
 modmex_lambda/event_handler/routing_fallbacks.py,sha256=vx23xyg4vEKCqGg1bxBP0OxRsN8NbMkAdehfcNiqwjw,3669
 modmex_lambda/event_handler/types.py,sha256=VRYaZVipqvwT_PyJ5teGADPIDyt_xRpqJ4bmqhd-lIA,1184
 modmex_lambda/event_handler/dependencies/__init__.py,sha256=KqYkgjAYNlZ2_PIDWAQSG4syIgeTdVmDQC5_lVjfyKI,288
@@ -42,7 +42,7 @@ modmex_lambda/shared/cookies.py,sha256=E2hTuht5_Xljw9zOQLW6vjsOWEpQSIqD2D3Tl1Co_
 modmex_lambda/shared/headers_serializer.py,sha256=Ao-wpx0cmy9E2ACrh7R7RIDUF0h24gax1AMtY_MjIWQ,2505
 modmex_lambda/shared/json_encoder.py,sha256=Mo4tlrhWvlBhhRYoPt2PAP6b_KsEKbk1pK6e5q0gbuk,1297
 modmex_lambda/shared/types.py,sha256=lH3i9MF7EQa1et8dD_qagEjlNzqznNHc0YZawp3toMc,134
-modmex_lambda-0.2.0.dist-info/METADATA,sha256=J_gbX6PVZhgRU5pv3fnY3pGeL1Mc1NzO9EznRQ4BTcI,10816
-modmex_lambda-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-modmex_lambda-0.2.0.dist-info/licenses/LICENSE,sha256=_C2TDTOsYeJvE4vn9VB51laKvleBKbdNnn96wJVtXhQ,1063
-modmex_lambda-0.2.0.dist-info/RECORD,,
+modmex_lambda-0.3.0.dist-info/METADATA,sha256=w87GM_X_jWixeYRoMBZEjx7KnlpkzMkhu6mIvro54E0,14774
+modmex_lambda-0.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+modmex_lambda-0.3.0.dist-info/licenses/LICENSE,sha256=_C2TDTOsYeJvE4vn9VB51laKvleBKbdNnn96wJVtXhQ,1063
+modmex_lambda-0.3.0.dist-info/RECORD,,