modmex-lambda 0.1.0__py3-none-any.whl

modmex_lambda/event_handler/dependencies/depends.py

@@ -0,0 +1,184 @@
+"""Dependency injection primitives for event handler resolvers."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any, Callable, get_args, get_origin, get_type_hints
+
+from modmex_lambda.event_handler.dependencies.compat import ModelField
+from modmex_lambda.event_handler.dependencies.types import CacheKey
+from modmex_lambda.event_handler.request import Request
+
+
+class Dependant:
+    """Route callable metadata used by dependency parsing and request validation."""
+
+    def __init__(
+        self,
+        *,
+        path_params: list[ModelField] | None = None,
+        query_params: list[ModelField] | None = None,
+        header_params: list[ModelField] | None = None,
+        cookie_params: list[ModelField] | None = None,
+        body_params: list[ModelField] | None = None,
+        return_param: ModelField | None = None,
+        name: str | None = None,
+        call: Callable[..., Any] | None = None,
+        dependencies: list[DependencyParam] | None = None,
+        path: str | None = None,
+    ) -> None:
+        self.path_params = path_params or []
+        self.query_params = query_params or []
+        self.header_params = header_params or []
+        self.cookie_params = cookie_params or []
+        self.body_params = body_params or []
+        self.return_param = return_param
+        self.dependencies = dependencies or []
+        self.name = name
+        self.call = call
+        self.path = path
+        self.cache_key: CacheKey = call
+
+
+class DependencyResolutionError(Exception):
+    """Raised when a dependency cannot be resolved."""
+
+
+class Depends:
+    def __init__(self, dependency: Callable[..., Any], *, use_cache: bool = True) -> None:
+        if not callable(dependency):
+            raise DependencyResolutionError(
+                f"Depends() requires a callable, got {type(dependency).__name__}: {dependency!r}",
+            )
+        self.dependency = dependency
+        self.use_cache = use_cache
+
+
+class _DependencyNode:
+    """Lightweight node in a dependency tree."""
+
+    def __init__(self, *, param_name: str, depends: Depends, sub_tree: DependencyTree) -> None:
+        self.param_name = param_name
+        self.depends = depends
+        self.dependant = sub_tree
+
+
+class DependencyTree:
+    """Lightweight dependency tree for call-time dependency resolution."""
+
+    def __init__(self, *, dependencies: list[_DependencyNode] | None = None) -> None:
+        self.dependencies = dependencies or []
+
+
+class DependencyParam:
+    """Dependency metadata attached to a route parameter."""
+
+    def __init__(self, *, param_name: str, depends: Depends, dependant: Dependant) -> None:
+        self.param_name = param_name
+        self.depends = depends
+        self.dependant = dependant
+
+
+def _get_depends_from_annotation(annotation: Any) -> Depends | None:
+    if get_origin(annotation) is Annotated:
+        for arg in get_args(annotation)[1:]:
+            if isinstance(arg, Depends):
+                return arg
+    return None
+
+
+def build_dependency_tree(func: Callable[..., Any]) -> DependencyTree:
+    """Build a dependency tree from Annotated parameters."""
+    try:
+        hints = get_type_hints(func, include_extras=True)
+    except Exception:
+        return DependencyTree()
+
+    dependencies: list[_DependencyNode] = []
+    for param_name, annotation in hints.items():
+        if param_name == "return":
+            continue
+
+        depends = _get_depends_from_annotation(annotation)
+        if depends is None:
+            continue
+
+        dependencies.append(
+            _DependencyNode(
+                param_name=param_name,
+                depends=depends,
+                sub_tree=build_dependency_tree(depends.dependency),
+            ),
+        )
+
+    return DependencyTree(dependencies=dependencies)
+
+
+def solve_dependencies(
+    *,
+    dependant: Dependant | DependencyTree,
+    request: Request | None = None,
+    dependency_overrides: dict[Callable[..., Any], Callable[..., Any]] | None = None,
+    dependency_cache: dict[Callable[..., Any], Any] | None = None,
+) -> dict[str, Any]:
+    """Resolve all Depends parameters for a route or lightweight dependency tree."""
+    from modmex_lambda.event_handler.request import Request as RequestClass
+
+    cache = dependency_cache if dependency_cache is not None else {}
+    overrides = dependency_overrides or {}
+    values: dict[str, Any] = {}
+
+    for dep in dependant.dependencies:
+        dependency = overrides.get(dep.depends.dependency, dep.depends.dependency)
+
+        if dep.depends.use_cache and dependency in cache:
+            values[dep.param_name] = cache[dependency]
+            continue
+
+        sub_values = solve_dependencies(
+            dependant=dep.dependant,
+            request=request,
+            dependency_overrides=overrides,
+            dependency_cache=cache,
+        )
+        sub_values.update(_request_injection_values(dependency, request, RequestClass))
+
+        try:
+            solved = dependency(**sub_values)
+        except Exception as exc:
+            dep_name = getattr(dependency, "__name__", repr(dependency))
+            raise DependencyResolutionError(
+                f"Failed to resolve dependency '{dep_name}' for parameter '{dep.param_name}': {exc}",
+            ) from exc
+
+        if dep.depends.use_cache:
+            cache[dependency] = solved
+
+        values[dep.param_name] = solved
+
+    return values
+
+
+def _request_injection_values(
+    dependency: Callable[..., Any],
+    request: Request | None,
+    request_class: type[Request],
+) -> dict[str, Request]:
+    if request is None:
+        return {}
+
+    try:
+        hints = get_type_hints(dependency)
+    except Exception:
+        return {}
+
+    return {name: request for name, annotation in hints.items() if annotation is request_class}
+
+
+__all__ = [
+    "Dependant",
+    "DependencyParam",
+    "Depends",
+    "_get_depends_from_annotation",
+    "build_dependency_tree",
+    "solve_dependencies",
+]

modmex_lambda/event_handler/dependencies/params.py

@@ -0,0 +1,317 @@
+from __future__ import annotations
+
+import inspect
+from enum import Enum
+from typing import Any, Literal, Annotated, get_args, get_origin
+
+from modmex import BaseModel, FieldInfo, create_model
+
+import modmex_lambda.event_handler.params as public_params
+from modmex_lambda.event_handler.dependencies.compat import (
+    ModelField,
+    Required,
+    copy_field_info,
+    field_annotation_is_scalar,
+    get_annotation_from_field_info,
+    lenient_issubclass,
+)
+from modmex_lambda.event_handler.dependencies.depends import Dependant
+from modmex_lambda.event_handler.dependencies.types import CacheKey
+from modmex_lambda.event_handler.response import Response
+
+
+class ParamTypes(Enum):
+    query = "query"
+    header = "header"
+    path = "path"
+    cookie = "cookie"
+
+
+class Param(FieldInfo):  # type: ignore[misc]
+    in_ = ParamTypes
+
+
+class Path(Param):  # type: ignore[misc]
+    in_ = ParamTypes.path
+
+
+class Query(Param):  # type: ignore[misc]
+    in_ = ParamTypes.query
+
+
+class Header(Param):  # type: ignore[misc]
+    in_ = ParamTypes.header
+
+
+class Cookie(Param):  # type: ignore[misc]
+    in_ = ParamTypes.cookie
+
+
+class Body(FieldInfo):  # type: ignore[misc]
+    pass
+
+
+class Form(Body):  # type: ignore[misc]
+    pass
+
+
+class UploadFile:
+    """Uploaded file value produced by multipart form parsing."""
+
+    __slots__ = ("content", "content_type", "filename")
+
+    def __init__(self, *, content: bytes, filename: str | None = None, content_type: str | None = None):
+        self.content = content
+        self.filename = filename
+        self.content_type = content_type
+
+    def __len__(self) -> int:
+        return len(self.content)
+
+    def __repr__(self) -> str:
+        return f"UploadFile(filename={self.filename!r}, content_type={self.content_type!r}, size={len(self.content)})"
+
+    @classmethod
+    def _validate(cls, v: Any) -> UploadFile:
+        if isinstance(v, cls):
+            return v
+        raise ValueError(f"Expected UploadFile, got {type(v).__name__}")
+
+
+class File(Form):  # type: ignore[misc]
+    pass
+
+
+_PUBLIC_PARAM_TO_INTERNAL: dict[type[Any], type[FieldInfo]] = {
+    public_params.Body: Body,
+    public_params.Query: Query,
+    public_params.Path: Path,
+    public_params.Header: Header,
+    public_params.Cookie: Cookie,
+}
+
+
+def _is_public_param_marker(value: Any) -> bool:
+    if isinstance(value, type):
+        return issubclass(value, public_params.Param)
+    return isinstance(value, public_params.Param)
+
+
+def _public_param_to_field_info(marker: Any) -> FieldInfo:
+    marker_type = marker if isinstance(marker, type) else type(marker)
+    alias = None if isinstance(marker, type) else marker.name
+    return _PUBLIC_PARAM_TO_INTERNAL[marker_type](alias=alias)
+
+
+def get_flat_dependant(
+    dependant: Dependant,
+    visited: list[CacheKey] | None = None,
+) -> Dependant:
+    visited = visited or []
+    visited.append(dependant.cache_key)
+
+    flat = Dependant(
+        path_params=dependant.path_params.copy(),
+        query_params=dependant.query_params.copy(),
+        header_params=dependant.header_params.copy(),
+        cookie_params=dependant.cookie_params.copy(),
+        body_params=dependant.body_params.copy(),
+        path=dependant.path,
+    )
+
+    for dep in dependant.dependencies:
+        if dep.dependant.cache_key in visited:
+            continue
+        sub_flat = get_flat_dependant(dep.dependant, visited=visited)
+        flat.path_params.extend(sub_flat.path_params)
+        flat.query_params.extend(sub_flat.query_params)
+        flat.header_params.extend(sub_flat.header_params)
+        flat.cookie_params.extend(sub_flat.cookie_params)
+        flat.body_params.extend(sub_flat.body_params)
+
+    return flat
+
+
+def analyze_param(
+    *,
+    param_name: str,
+    annotation: Any,
+    value: Any,
+    is_path_param: bool,
+    is_response_param: bool,
+) -> ModelField | None:
+    field_info, type_annotation = _resolve_field_info(annotation, value, is_path_param, is_response_param)
+
+    if isinstance(value, FieldInfo):
+        if field_info is not None:
+            raise AssertionError("Cannot use a FieldInfo as a parameter annotation and pass a FieldInfo as a value")
+        field_info = value
+        field_info.annotation = type_annotation
+
+    if field_info is None:
+        field_info = _default_field_info(type_annotation, value, is_path_param)
+
+    if is_response_param:
+        field_info.default = Required
+
+    return _create_model_field(field_info, type_annotation, param_name, is_path_param, is_response_param)
+
+
+def _resolve_field_info(
+    annotation: Any,
+    value: Any,
+    is_path_param: bool,
+    is_response_param: bool,
+) -> tuple[FieldInfo | None, Any]:
+    if annotation is inspect.Signature.empty:
+        return None, Any
+
+    origin = get_origin(annotation)
+    args = get_args(annotation)
+
+    if origin is Annotated:
+        return _resolve_annotated(annotation, value, is_path_param)
+    if _is_public_param_marker(origin):
+        return _field_from_public_marker(origin, args[0] if args else Any, value, is_path_param)
+    if _is_public_param_marker(annotation):
+        return _field_from_public_marker(annotation, Any, value, is_path_param)
+    if origin is Response:
+        (inner_type,) = args
+        return _resolve_field_info(inner_type, value, False, True)
+    if is_response_param and origin is tuple and len(args) == 2:
+        inner_type = args[0]
+        if get_origin(inner_type) is Annotated:
+            return _resolve_annotated(inner_type, value, False)
+        return None, inner_type
+
+    return None, annotation
+
+
+def _field_from_public_marker(
+    marker: Any,
+    type_annotation: Any,
+    value: Any,
+    is_path_param: bool,
+) -> tuple[FieldInfo, Any]:
+    field_info = _public_param_to_field_info(marker)
+    field_info.annotation = type_annotation
+    _set_field_default(field_info, value, is_path_param)
+    return field_info, type_annotation
+
+
+def _default_field_info(type_annotation: Any, value: Any, is_path_param: bool) -> FieldInfo:
+    default = value if value is not inspect.Signature.empty else Required
+    if is_path_param:
+        return Path(annotation=type_annotation)
+    if field_annotation_is_scalar(type_annotation):
+        return Query(annotation=type_annotation, default=default)
+    return Body(annotation=type_annotation, default=default)
+
+
+def _resolve_annotated(annotation: Any, value: Any, is_path_param: bool) -> tuple[FieldInfo | None, Any]:
+    annotated_args = get_args(annotation)
+    type_annotation = annotated_args[0]
+    markers: list[FieldInfo] = []
+    metadata: list[Any] = []
+
+    for item in annotated_args[1:]:
+        marker = _annotation_to_field_info(item)
+        if marker is None:
+            metadata.append(item)
+        else:
+            markers.append(marker)
+
+    if len(markers) > 1:
+        raise AssertionError("Only one FieldInfo can be used per parameter")
+
+    if metadata:
+        type_annotation = Annotated[(type_annotation, *metadata)]
+
+    if not markers:
+        return None, type_annotation
+
+    field_info = copy_field_info(field_info=markers[0], annotation=type_annotation)
+    _set_field_default(field_info, value, is_path_param)
+    return field_info, type_annotation
+
+
+def _annotation_to_field_info(annotation: Any) -> FieldInfo | None:
+    if isinstance(annotation, FieldInfo):
+        return annotation
+    if isinstance(annotation, type) and issubclass(annotation, FieldInfo):
+        return annotation()
+    if _is_public_param_marker(annotation):
+        return _public_param_to_field_info(annotation)
+    return None
+
+
+def _set_field_default(field_info: FieldInfo, value: Any, is_path_param: bool) -> None:
+    if field_info.default not in [None, Required]:
+        raise AssertionError("FieldInfo needs to have a default value of None or Required")
+
+    if value is inspect.Signature.empty:
+        field_info.default = Required
+        return
+
+    if is_path_param:
+        raise AssertionError("Cannot use a FieldInfo as a path parameter and pass a value")
+
+    if isinstance(field_info, Header) and isinstance(value, str) and field_info.alias is None:
+        field_info.alias = value.lower()
+        field_info.default = Required
+        return
+
+    field_info.default = value
+
+
+def create_response_field(
+    name: str,
+    type_: Any,
+    default: Any | None = None,
+    field_info: FieldInfo | None = None,
+    alias: str | None = None,
+    mode: Literal["validation", "serialization"] = "validation",
+) -> ModelField:
+    field_info = field_info or FieldInfo(annotation=type_, default=default, alias=alias)
+    return ModelField(name=name, field_info=field_info, mode=mode)
+
+
+def _apply_header_model_aliases(field_info: FieldInfo, type_annotation: Any) -> tuple[FieldInfo, Any]:
+    if not isinstance(field_info, Header) or not lenient_issubclass(type_annotation, BaseModel):
+        return field_info, type_annotation
+
+    header_model = create_model(
+        f"{type_annotation.__name__}WithHeaderAliases",
+        __base__=type_annotation,
+        __config__={"alias_generator": lambda name: name.replace("_", "-")},
+    )
+    field_info.annotation = header_model
+    return field_info, header_model
+
+
+def _create_model_field(
+    field_info: FieldInfo | None,
+    type_annotation: Any,
+    param_name: str,
+    is_path_param: bool,
+    is_response_param: bool = False,
+) -> ModelField | None:
+    if field_info is None:
+        return None
+
+    if is_path_param and not isinstance(field_info, Path):
+        raise AssertionError("Path parameters must be of type Path")
+    if not is_path_param and isinstance(field_info, Param) and getattr(field_info, "in_", None) is None:
+        field_info.in_ = ParamTypes.query
+
+    field_info, type_annotation = _apply_header_model_aliases(field_info, type_annotation)
+    use_annotation = get_annotation_from_field_info(type_annotation, field_info, param_name)
+
+    return create_response_field(
+        name=param_name,
+        type_=use_annotation,
+        default=field_info.default,
+        alias=field_info.alias,
+        field_info=field_info,
+        mode="serialization" if is_response_param else "validation",
+    )

modmex_lambda/event_handler/dependencies/types.py

@@ -0,0 +1,14 @@
+import types
+from enum import Enum
+from modmex import BaseModel
+from typing import Union, Any, Dict, Set, Type, Callable
+
+UnionType = getattr(types, "UnionType", Union)
+
+IncEx = Union[Set[int], Set[str], Dict[int, Any], Dict[str, Any]]
+
+TypeModelOrEnum = Union[Type[BaseModel], Type[Enum]]
+
+ModelNameMap = Dict[TypeModelOrEnum, str]
+
+CacheKey = Union[Callable[..., Any], None]

modmex_lambda/event_handler/exception_handler.py

@@ -0,0 +1,70 @@
+from __future__ import annotations
+
+from typing import Mapping, Any
+from collections.abc import Callable
+
+
+class ExceptionHandlerManager:
+
+    def __init__(self):
+        """Initialize an empty dictionary to store exception handlers."""
+        self._exception_handlers: dict[type[Exception], Callable] = {}
+
+    def exception_handler(self, exc_class: type[Exception] | list[type[Exception]]):
+        """
+        A decorator function that registers a handler for one or more exception types.
+        """
+        classes = exc_class if isinstance(exc_class, list) else [exc_class]
+        
+        def register_exception_handler(func: Callable)-> Callable[[Exception], Any]:
+            for cls in classes:
+                self._exception_handlers[cls] = func
+            return func
+
+        return register_exception_handler
+
+    def lookup_exception_handler(self, exp_type: type) -> Callable | None:
+        for cls in exp_type.__mro__:
+            if cls in self._exception_handlers:
+                return self._exception_handlers[cls]
+        return None
+
+    def update_exception_handlers(self, handlers: Mapping[type[Exception], Callable]) -> None:
+        """
+        Updates the exception handlers dictionary with new handler mappings.
+        This method allows bulk updates of exception handlers by providing a dictionary
+        mapping exception types to handler functions.
+        Parameters
+        ----------
+        handlers : Mapping[Type[Exception], Callable]
+            A dictionary mapping exception types to handler functions.
+        Example
+        -------
+        >>> def handle_value_error(e):
+        ...     print(f"Value error: {e}")
+        ...
+        >>> def handle_key_error(e):
+        ...     print(f"Key error: {e}")
+        ...
+        >>> handler_manager.update_exception_handlers({
+        ...     ValueError: handle_value_error,
+        ...     KeyError: handle_key_error
+        ... })
+        """
+        self._exception_handlers.update(handlers)
+
+    def get_registered_handlers(self) -> dict[type[Exception], Callable]:
+        """
+        Returns all registered exception handlers.
+        Returns
+        -------
+        Dict[Type[Exception], Callable]
+            A dictionary mapping exception types to their handler functions.
+        """
+        return self._exception_handlers.copy()
+
+    def clear_handlers(self) -> None:
+        """
+        Clears all registered exception handlers.
+        """
+        self._exception_handlers.clear()

modmex_lambda/event_handler/exceptions.py

@@ -0,0 +1,72 @@
+"""Framework exceptions with API Gateway friendly defaults."""
+from collections.abc import Sequence
+from http import HTTPStatus
+from typing import Any
+from modmex import ValidationError
+
+
+class ValidationException(Exception):
+    """
+    Base exception for all validation errors
+    """
+
+    def __init__(self, errors: Sequence[Any]) -> None:
+        self._errors = errors
+
+    def errors(self) -> Sequence[Any]:
+        return self._errors
+
+class ServiceError(Exception):
+    """HTTP Service Error"""
+
+    def __init__(self, status_code: int, msg: str | dict):
+        """
+        Parameters
+        ----------
+        status_code: int
+            HTTP status code
+        msg: str | dict
+            Error message. Can be a string or a dictionary
+        """
+        self.status_code = status_code
+        self.msg = msg
+
+
+class RequestValidationError(ValidationException):
+    """Raised when request validation fails."""
+
+
+
+class NotFoundError(ServiceError):
+    """Raised when no route matches a request path."""
+    
+    def __init__(self, msg: str | dict = "Not Found"):
+        super().__init__(HTTPStatus.NOT_FOUND, msg)
+
+
+class MethodNotAllowedError(ServiceError):
+    """Raised when a path exists but the HTTP method is not allowed."""
+    
+    def __init__(self, msg: str | dict = "Method Not Allowed"):
+        super().__init__(HTTPStatus.METHOD_NOT_ALLOWED, msg)
+
+
+class BadRequestError(ServiceError):
+    """Raised when an incoming event cannot be normalized."""
+    
+    def __init__(self, msg: str | dict = "Bad Request"):
+        super().__init__(HTTPStatus.BAD_REQUEST, msg)
+
+
+class UnauthorizedError(ServiceError):
+    """Raised when a request is not authenticated."""
+    
+    def __init__(self, msg: str | dict = "Unauthorized"):
+        super().__init__(HTTPStatus.UNAUTHORIZED, msg)
+
+
+class ForbiddenError(ServiceError):
+    """Raised when a request is authenticated but not authorized."""
+    
+    def __init__(self, msg: str | dict = "Forbidden"):
+        super().__init__(HTTPStatus.FORBIDDEN, msg)