modmex-lambda 0.1.0__py3-none-any.whl

modmex_lambda-0.1.0.dist-info/METADATA

@@ -0,0 +1,375 @@
+Metadata-Version: 2.4
+Name: modmex-lambda
+Version: 0.1.0
+Summary: Ultra-lightweight AWS Lambda utilities for API Gateway routing and event handling.
+Author: Modmex
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: modmex<2.0.0,>=1.1.10
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# modmex-lambda
+
+Ultra-lightweight AWS Lambda utilities for API Gateway-first workloads.
+
+`modmex-lambda` is a Lambda utility layer, not an ASGI framework. It focuses on
+API Gateway proxy events, fast routing, request binding, response serialization,
+middleware, dependency injection, event source wrappers, parsing, and structured
+logging with a small dependency footprint.
+
+## Install
+
+```bash
+pip install modmex-lambda
+```
+
+For local development:
+
+```bash
+poetry install --extras dev
+poetry run pytest -q
+```
+
+## API Gateway Resolvers
+
+Choose the resolver that matches the API Gateway payload version used by your
+Lambda integration:
+
+- `ApiGatewayRestResolver` for REST API payload v1.
+- `ApiGatewayHttpResolver` for HTTP API payload v2 and Lambda Function URLs.
+
+```python
+from modmex_lambda import ApiGatewayHttpResolver
+
+app = ApiGatewayHttpResolver()
+
+
+@app.get("/ping")
+def ping():
+    return {"message": "pong"}
+
+
+handler = app.handler
+```
+
+The internal base resolver is intentionally not exported from the package root;
+application code should select REST or HTTP explicitly.
+
+## Routing
+
+Routes are declared with decorators:
+
+```python
+@app.get("/users/<user_id>")
+def get_user(user_id: int):
+    return {"user_id": user_id}
+
+
+@app.post("/users", status_code=201)
+def create_user():
+    return {"id": 42}
+```
+
+Supported route decorators include `get`, `post`, `put`, `patch`, `delete`,
+`options`, and `any`.
+
+Routers can also strip deployment prefixes:
+
+```python
+app = ApiGatewayHttpResolver(strip_prefixes=["/prod"])
+```
+
+## Request Binding
+
+Use `typing.Annotated` with the public parameter markers:
+
+- `Path()`
+- `Query()`
+- `Header()`
+- `Cookie()`
+- `Body()`
+
+```python
+from typing import Annotated
+
+from modmex import BaseModel
+from modmex_lambda import ApiGatewayHttpResolver, Request
+from modmex_lambda.event_handler.params import Body, Header, Path, Query
+
+app = ApiGatewayHttpResolver()
+
+
+class CreateUserRequest(BaseModel):
+    name: str
+    age: int | None = None
+
+
+@app.post("/users", status_code=201)
+def create_user(
+    payload: Annotated[CreateUserRequest, Body()],
+    tenant_id: Annotated[str, Header(name="x-tenant-id")],
+    request: Request,
+):
+    return {
+        "id": 42,
+        "tenant_id": tenant_id,
+        "route": request.route,
+        "payload": payload.model_dump(),
+    }
+
+
+@app.get("/users/<user_id>")
+def get_user(
+    user_id: Annotated[int, Path()],
+    include_orders: Annotated[bool, Query()] = False,
+):
+    return {"user_id": user_id, "include_orders": include_orders}
+```
+
+For headers, simple scalar parameters can use `Header(name="x-header-name")`.
+Header models are also supported; field names are exposed as dash-case aliases.
+
+```python
+class HeaderModel(BaseModel):
+    x_tenant_id: str
+
+
+@app.get("/me")
+def me(headers: Annotated[HeaderModel, Header()]):
+    return {"tenant": headers.x_tenant_id}
+```
+
+## Responses
+
+Route return values are converted to API Gateway proxy responses:
+
+- `dict` and `list` become JSON responses.
+- `str` becomes a text response.
+- `bytes` are base64 encoded.
+- `None` returns an empty response.
+- `(body, status_code)` sets the response status.
+- `Response` gives full control over status, headers, cookies, and content type.
+
+```python
+from modmex_lambda import Response
+from modmex_lambda.shared.cookies import Cookie
+
+
+@app.get("/session")
+def session():
+    return Response(
+        status_code=200,
+        body={"ok": True},
+        cookies=[Cookie("seen", "true", secure=True)],
+    )
+```
+
+REST API responses use `multiValueHeaders`; HTTP API responses use the v2
+`headers` and `cookies` shape.
+
+## Middleware
+
+Middleware receives the resolver instance and a `next_middleware` callable.
+Global middleware can be registered with `use` or `@app.middleware`; route
+middleware can be attached per route.
+
+```python
+from modmex_lambda import Response
+from modmex_lambda.event_handler.middlewares import NextMiddleware
+
+
+@app.middleware
+def require_auth(app: ApiGatewayHttpResolver, next_middleware: NextMiddleware) -> Response:
+    if app.current_event.headers.get("x-auth") != "ok":
+        return Response(status_code=401, body={"message": "Unauthorized"})
+    return next_middleware(app)
+```
+
+Middleware also wraps routing fallbacks, so `404` and `405` responses still flow
+through the middleware chain.
+
+## Dependency Injection
+
+`Depends` supports nested dependency trees, request-aware dependencies,
+per-invocation caching, and overrides for tests.
+
+```python
+from typing import Annotated
+
+from modmex_lambda import Depends, Request
+from modmex_lambda.event_handler.params import Path
+
+
+class UserRepository:
+    def __init__(self, *, tenant_id: str, token: str):
+        self.tenant_id = tenant_id
+        self.token = token
+
+    def get_user(self, user_id: int) -> dict:
+        # Replace this with a database or service call.
+        return {"id": user_id, "tenant_id": self.tenant_id}
+
+
+def get_token() -> str:
+    return "token"
+
+
+def get_tenant_id(request: Request) -> str:
+    return request.headers["x-tenant-id"]
+
+
+def get_user_repository(
+    tenant_id: Annotated[str, Depends(get_tenant_id)],
+    token: Annotated[str, Depends(get_token)],
+) -> UserRepository:
+    return UserRepository(tenant_id=tenant_id, token=token)
+
+
+@app.get("/users/<user_id>")
+def get_user(
+    user_id: Annotated[int, Path()],
+    repository: Annotated[UserRepository, Depends(get_user_repository)],
+):
+    return repository.get_user(user_id)
+```
+
+Disable dependency caching when a dependency must run every time:
+
+```python
+def next_counter() -> int:
+    ...
+
+
+@app.get("/counter")
+def counter(value: Annotated[int, Depends(next_counter, use_cache=False)]):
+    return {"value": value}
+```
+
+For tests, set `app.dependency_overrides`:
+
+```python
+app.dependency_overrides[get_token] = lambda: "test-token"
+```
+
+## Exception Handling
+
+Built-in error responses:
+
+- request validation errors return `400`.
+- `NotFoundError` returns `404`.
+- `MethodNotAllowedError` returns `405`.
+- `UnauthorizedError` returns `401`.
+- `ForbiddenError` returns `403`.
+
+Custom handlers can be registered per exception type. The most specific handler
+wins.
+
+```python
+from modmex_lambda import Response
+
+
+class DomainError(Exception):
+    pass
+
+
+@app.exception_handler(DomainError)
+def on_domain_error(exc: DomainError):
+    return Response(status_code=409, body={"message": str(exc)})
+```
+
+If a custom exception handler raises, the resolver falls back to the default
+error response when one exists.
+
+## CORS
+
+Pass `CORSConfig` to the resolver to add CORS headers and automatic preflight
+behavior.
+
+```python
+from modmex_lambda import ApiGatewayHttpResolver
+from modmex_lambda.event_handler.cors import CORSConfig
+
+app = ApiGatewayHttpResolver(
+    cors=CORSConfig(
+        allow_origin="https://app.example",
+        allow_headers=["X-Tenant-Id"],
+        allow_credentials=True,
+    ),
+)
+```
+
+## Parser
+
+```python
+from modmex_lambda.parser import event_parser, parse
+
+parsed = parse(event={"name": "Ada"}, model=MyModel)
+
+
+@event_parser(model=MyModel)
+def lambda_handler(event: MyModel, context):
+    ...
+```
+
+## Event Source Data Classes
+
+Current scoped data classes include:
+
+- `APIGatewayProxyEvent` and `APIGatewayProxyEventV2`
+- `APIGatewayRestEvent` and `APIGatewayHttpEvent` aliases
+- `APIGatewayAuthorizerEvent`
+- `APIGatewayWebSocketEvent`
+- Cognito User Pool trigger wrappers
+
+```python
+from modmex_lambda.data_classes import APIGatewayHttpEvent
+from modmex_lambda.event_sources import event_source
+
+
+@event_source(data_class=APIGatewayHttpEvent)
+def lambda_handler(event: APIGatewayHttpEvent, context):
+    return {"path": event.path}
+```
+
+## Validation
+
+Modmex is the default validation and coercion engine. Pydantic is not required
+for normal operation.
+
+## Logging
+
+```python
+from modmex_lambda import Logger
+
+logger = Logger(service="users")
+
+
+def lambda_handler(event, context):
+    logger.append_keys(tenant_id="mx")
+    logger.info("request received")
+```
+
+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
+
+- Event source scope is intentionally focused on API Gateway and Cognito.
+- OpenAPI/Swagger generation is not implemented.
+- Async resolver pipelines are not implemented yet.

modmex_lambda-0.1.0.dist-info/RECORD

@@ -0,0 +1,48 @@
+modmex_lambda/__init__.py,sha256=3gWLZwuPGrvvjTsycbsvGd4Noh4bEj87MwP32IyNrjU,1966
+modmex_lambda/event_sources.py,sha256=eLTEN1g9JF2Nk09fMcJn43dBz8BKwCOrtxmZkzr99sM,1714
+modmex_lambda/exceptions.py,sha256=GL6ZZKhXr0BqfCsGwzookBrUJ1M7JIU2Ju3vWdyna_s,128
+modmex_lambda/logging.py,sha256=FFINAvMu25d0Ieow-Wa8fEjr9xvtRtPgtLixsDGFPHc,3335
+modmex_lambda/params.py,sha256=s7cnrW2NSCwWyQ_odn0b_uQJJn_aDR0JO6XUAFKI3PY,131
+modmex_lambda/parser.py,sha256=BO2PG1YHZsRbHxqcd4rKehJDkBoipAQjAgXi-E7mysM,1544
+modmex_lambda/request.py,sha256=2LgG5bKFhFL8xNGaGJTK_djX0nSQOwCmjuPN54ORdL8,129
+modmex_lambda/resolver.py,sha256=6EvyxbcrTqNy-xb8l-Pz8z3gXeuYWyQErZVyY5w--8o,126
+modmex_lambda/response.py,sha256=n7ZjcV13IR_ohtxEs8O6T6xVhNFs0DiLlUej8PpO0no,132
+modmex_lambda/routing.py,sha256=nCIo7UoOn9W6oZXYjjw5GxMp80jZ6nbuh4WEN6f5dSg,132
+modmex_lambda/validation.py,sha256=64uWzSnkxzN1t7DAqC_0TYzhupQUtAWnrLATEFAEfzs,7130
+modmex_lambda/data_classes/__init__.py,sha256=puf_FWi1HaqzoPw2mhA-gUUJB_8v6x1ndp0dgoGRDp0,1711
+modmex_lambda/data_classes/api_gateway_authorizer_event.py,sha256=Qk7RLWm_L67VwWbu8VRmJTUlDcAJDlFvVp-cCKm2QhA,1037
+modmex_lambda/data_classes/api_gateway_proxy_event.py,sha256=fetGgKG4QFpPXu0lImtei29G1bgNF5hNZOdFdW8zP90,10957
+modmex_lambda/data_classes/api_gateway_websocket_event.py,sha256=EGFqQ4SrC-ssb509UzfNLWpPm7gdtleoYz5Pvb2fIwU,1031
+modmex_lambda/data_classes/cognito_user_pool_event.py,sha256=DwHa9xtqpFYnFKdUi1Y9RRgxvkVGJQXhFkRh7_4iAf4,18582
+modmex_lambda/data_classes/common.py,sha256=8saOnaCxH25G-jQumUJMg6CuOhuJ6ugw4vAWH-Fn4Ls,13656
+modmex_lambda/event_handler/__init__.py,sha256=4uB7HhYgShpgXJECQhvxJId8Y1Cbkz69M0rpuSxN0I8,1327
+modmex_lambda/event_handler/api_gateway.py,sha256=YdgeyObhdPsBApQxnSQd-JykqJ6WKsrIqgKw5r9X8d0,11795
+modmex_lambda/event_handler/constants.py,sha256=x53p_BZw2lmISpkO5v6d1nfuP-De9uUsUtwgJLaBHKw,28
+modmex_lambda/event_handler/content_types.py,sha256=FcnCaAVhEOewQXAbkStMBNC63NFMxqwmEFnXcGholug,282
+modmex_lambda/event_handler/cors.py,sha256=j8H81NdPxqRl5ikW8Wdf7o6pEIx7dGkAsCtSysYI1nc,3516
+modmex_lambda/event_handler/exception_handler.py,sha256=zJmM_kUwq3vnzx3ETlgPs2JokQbauweuUJrCDYsPZwg,2491
+modmex_lambda/event_handler/exceptions.py,sha256=wPova4geWuyuFsP43xyy0MIxOvDwVx-CfgwnF0QcZbk,2025
+modmex_lambda/event_handler/gateway_response.py,sha256=9V5d8Ar7JfrsFRWk02GKzJN8maSIHdl4fLlAlgmzJSQ,3728
+modmex_lambda/event_handler/middlewares.py,sha256=oOsQ0nOl7lc_N-kt8wTx7qOXNE5VtRjDEVdcsnYb-Sk,925
+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=ofRSEfWxxAayThjgsBzZ6ZQaSFwtFxnpp1LDp-za2vY,16077
+modmex_lambda/event_handler/routing_fallbacks.py,sha256=vx23xyg4vEKCqGg1bxBP0OxRsN8NbMkAdehfcNiqwjw,3669
+modmex_lambda/event_handler/types.py,sha256=VKl50yStngGK1vBsPVDLQnO8zffgqL9T1StPIVY82qo,1060
+modmex_lambda/event_handler/dependencies/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modmex_lambda/event_handler/dependencies/compat.py,sha256=MPEJ9EKNja_ys4XLGIm8vTgN7Z96nmuqYHTvixHFR9A,7599
+modmex_lambda/event_handler/dependencies/dependant.py,sha256=LWo2r6BZkOKo26tXr5g9vJ_C9Yrixf6iiFsAfM66JXw,9306
+modmex_lambda/event_handler/dependencies/dependency_middleware.py,sha256=c_N7UgtbAVYC6xbfn_MaW7zYQxi5pSSdTeIRaz703Ak,14999
+modmex_lambda/event_handler/dependencies/depends.py,sha256=X174dJZ_m6kYvcUvy2IJ7UuLRDV8lH2Jgiht5PQRt8w,5932
+modmex_lambda/event_handler/dependencies/params.py,sha256=bc208GHiXCfm1V-GLeIMm8-ypZ8P8Q9qUKQkK2Vh1Fg,10085
+modmex_lambda/event_handler/dependencies/types.py,sha256=5VA8zl-EjQDNKXOrNT7sRv_vNs40Lz8aMP-sf-lf8sk,376
+modmex_lambda/shared/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+modmex_lambda/shared/cookies.py,sha256=E2hTuht5_Xljw9zOQLW6vjsOWEpQSIqD2D3Tl1Co_s0,2076
+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.1.0.dist-info/METADATA,sha256=HOUUd4hbMrZTGBW045M_ltsC9-myVmZiUV9Jt51JHRo,8936
+modmex_lambda-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+modmex_lambda-0.1.0.dist-info/licenses/LICENSE,sha256=_C2TDTOsYeJvE4vn9VB51laKvleBKbdNnn96wJVtXhQ,1063
+modmex_lambda-0.1.0.dist-info/RECORD,,

modmex_lambda-0.1.0.dist-info/WHEEL

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

modmex_lambda-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 modmex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.