fix: document the new methods

Author: rubenfonseca

aws_lambda_powertools/event_handler/api_gateway.py

@@ -4,6 +4,7 @@
 import re
 import traceback
 import warnings
+import zlib
 from abc import ABC, abstractmethod
 from enum import Enum
 from functools import partial
@@ -23,7 +24,6 @@
     Union,
 )
 
-import zlib
 from pydantic.fields import ModelField
 from pydantic.schema import get_flat_models_from_fields, get_model_name_map, model_process_schema
 
@@ -685,7 +685,7 @@ def get_openapi_schema(
 
         for route in all_routes:
             dependant = get_dependant(
-                path=route.func.__name__,
+                path=route.path,
                 call=route.func,
             )
 

aws_lambda_powertools/event_handler/openapi/dependant.py

@@ -7,12 +7,38 @@
 
 from aws_lambda_powertools.event_handler.openapi.params import Dependant, Param, ParamTypes, analyze_param
 
+"""
+This turns the opaque function signature into typed, validated models.
+
+It relies on Pydantic's typing and validation to achieve this in a declarative way.
+This enables traits like autocompletion, validation, and declarative structure vs imperative parsing.
+
+This code parses an OpenAPI operation handler function signature into Pydantic models. It uses inspect to get the
+signature and regex to parse path parameters. Each parameter is analyzed to extract its type annotation and generate
+a corresponding Pydantic field, which are added to a Dependant model. Return values are handled similarly.
+
+This modeling allows for type checking, automatic parameter name/location/type extraction, and input validation -
+turning the opaque signature into validated models. It relies on Pydantic's typing and validation for a declarative
+approach over imperative parsing, enabling autocompletion, validation and structure.
+"""
+
 
 def add_param_to_fields(
     *,
     field: ModelField,
     dependant: Dependant,
 ) -> None:
+    """
+    Adds a parameter to the list of parameters in the dependant model.
+
+    Parameters
+    ----------
+    field: ModelField
+        The field to add
+    dependant: Dependant
+        The dependant model to add the field to
+
+    """
     field_info = cast(Param, field.field_info)
     if field_info.in_ == ParamTypes.path:
         dependant.path_params.append(field)
@@ -26,15 +52,34 @@ def add_param_to_fields(
 
 
 def get_typed_annotation(annotation: Any, globalns: Dict[str, Any]) -> Any:
+    """
+    Evaluates a type annotation, which can be a string or a ForwardRef.
+    """
     if isinstance(annotation, str):
         annotation = ForwardRef(annotation)
         annotation = evaluate_forwardref(annotation, globalns, globalns)
     return annotation
 
 
 def get_typed_signature(call: Callable[..., Any]) -> inspect.Signature:
+    """
+    Returns a typed signature for a callable, resolving forward references.
+
+    Parameters
+    ----------
+    call: Callable[..., Any]
+        The callable to get the signature for
+
+    Returns
+    -------
+    inspect.Signature
+        The typed signature
+    """
     signature = inspect.signature(call)
+
+    # Gets the global namespace for the call. This is used to resolve forward references.
     globalns = getattr(call, "__global__", {})
+
     typed_params = [
         inspect.Parameter(
             name=param.name,
@@ -45,6 +90,7 @@ def get_typed_signature(call: Callable[..., Any]) -> inspect.Signature:
         for param in signature.parameters.values()
     ]
 
+    # If the return annotation is not empty, add it to the signature.
     if signature.return_annotation is not inspect.Signature.empty:
         return_param = inspect.Parameter(
             name="Return",
@@ -58,7 +104,21 @@ def get_typed_signature(call: Callable[..., Any]) -> inspect.Signature:
 
 
 def get_path_param_names(path: str) -> Set[str]:
-    return set(re.findall("{(.*?)}", path))
+    """
+    Returns the path parameter names from a path template. Those are the strings between < and >.
+
+    Parameters
+    ----------
+    path: str
+        The path template
+
+    Returns
+    -------
+    Set[str]
+        The path parameter names
+
+    """
+    return set(re.findall("<(.*?)>", path))
 
 
 def get_dependant(
@@ -67,17 +127,39 @@ def get_dependant(
     call: Callable[..., Any],
     name: Optional[str] = None,
 ) -> Dependant:
+    """
+    Returns a dependant model for a handler function. A dependant model is a model that contains
+    the parameters and return value of a handler function.
+
+    Parameters
+    ----------
+    path: str
+        The path template
+    call: Callable[..., Any]
+        The handler function
+    name: str, optional
+        The name of the handler function
+
+    Returns
+    -------
+    Dependant
+        The dependant model for the handler function
+    """
     path_param_names = get_path_param_names(path)
     endpoint_signature = get_typed_signature(call)
     signature_params = endpoint_signature.parameters
+
     dependant = Dependant(
         call=call,
         name=name,
         path=path,
     )
 
     for param_name, param in signature_params.items():
+        # If the parameter is a path parameter, we need to set the in_ field to "path".
         is_path_param = param_name in path_param_names
+
+        # Analyze the parameter to get the type annotation and the Pydantic field.
         type_annotation, param_field = analyze_param(
             param_name=param_name,
             annotation=param.annotation,
@@ -88,6 +170,7 @@ def get_dependant(
 
         add_param_to_fields(field=param_field, dependant=dependant)
 
+    # If the return annotation is not empty, add it to the dependant model.
     return_annotation = endpoint_signature.return_annotation
     if return_annotation is not inspect.Signature.empty:
         type_annotation, param_field = analyze_param(

aws_lambda_powertools/event_handler/openapi/models.py

@@ -7,7 +7,13 @@
 
 PYDANTIC_V2 = PYDANTIC_VERSION.startswith("2.")
 
+"""
+The code defines Pydantic models for the various OpenAPI objects like OpenAPI, PathItem, Operation, Parameter etc.
+These models can be used to parse OpenAPI JSON/YAML files into Python objects, or generate OpenAPI from Python data.
+"""
 
+
+# https://swagger.io/specification/#contact-object
 class Contact(BaseModel):
     name: Optional[str] = None
     url: Optional[AnyUrl] = None
@@ -21,6 +27,7 @@ class Config:
             extra = "allow"
 
 
+# https://swagger.io/specification/#license-object
 class License(BaseModel):
     name: str
     identifier: Optional[str] = None
@@ -35,6 +42,7 @@ class Config:
             extra = "allow"
 
 
+# https://swagger.io/specification/#info-object
 class Info(BaseModel):
     title: str
     summary: Optional[str] = None
@@ -53,6 +61,7 @@ class Config:
             extra = "allow"
 
 
+# https://swagger.io/specification/#server-variable-object
 class ServerVariable(BaseModel):
     enum: Annotated[Optional[List[str]], Field(min_length=1)] = None
     default: str
@@ -67,6 +76,7 @@ class Config:
             extra = "allow"
 
 
+# https://swagger.io/specification/#server-object
 class Server(BaseModel):
     url: Union[AnyUrl, str]
     description: Optional[str] = None
@@ -81,15 +91,18 @@ class Config:
             extra = "allow"
 
 
+# https://swagger.io/specification/#reference-object
 class Reference(BaseModel):
     ref: str = Field(alias="$ref")
 
 
+# https://swagger.io/specification/#discriminator-object
 class Discriminator(BaseModel):
     propertyName: str
     mapping: Optional[Dict[str, str]] = None
 
 
+# https://swagger.io/specification/#xml-object
 class XML(BaseModel):
     name: Optional[str] = None
     namespace: Optional[str] = None
@@ -106,6 +119,7 @@ class Config:
             extra = "allow"
 
 
+# https://swagger.io/specification/#external-documentation-object
 class ExternalDocumentation(BaseModel):
     description: Optional[str] = None
     url: AnyUrl
@@ -119,6 +133,7 @@ class Config:
             extra = "allow"
 
 
+# https://swagger.io/specification/#schema-object
 class Schema(BaseModel):
     # Ref: JSON Schema 2020-12: https://json-schema.org/draft/2020-12/json-schema-core.html#name-the-json-schema-core-vocabu
     # Core Vocabulary
@@ -212,6 +227,7 @@ class Config:
 SchemaOrBool = Union[Schema, bool]
 
 
+# https://swagger.io/specification/#example-object
 class Example(BaseModel):
     summary: Optional[str] = None
     description: Optional[str] = None
@@ -234,6 +250,7 @@ class ParameterInType(Enum):
     cookie = "cookie"
 
 
+# https://swagger.io/specification/#encoding-object
 class Encoding(BaseModel):
     contentType: Optional[str] = None
     headers: Optional[Dict[str, Union["Header", Reference]]] = None
@@ -250,6 +267,7 @@ class Config:
             extra = "allow"
 
 
+# https://swagger.io/specification/#media-type-object
 class MediaType(BaseModel):
     schema_: Optional[Union[Schema, Reference]] = Field(default=None, alias="schema")
     example: Optional[Any] = None
@@ -265,6 +283,7 @@ class Config:
             extra = "allow"
 
 
+# https://swagger.io/specification/#parameter-object
 class ParameterBase(BaseModel):
     description: Optional[str] = None
     required: Optional[bool] = None
@@ -297,6 +316,7 @@ class Header(ParameterBase):
     pass
 
 
+# https://swagger.io/specification/#request-body-object
 class RequestBody(BaseModel):
     description: Optional[str] = None
     content: Dict[str, MediaType]
@@ -311,6 +331,7 @@ class Config:
             extra = "allow"
 
 
+# https://swagger.io/specification/#link-object
 class Link(BaseModel):
     operationRef: Optional[str] = None
     operationId: Optional[str] = None
@@ -328,6 +349,7 @@ class Config:
             extra = "allow"
 
 
+# https://swagger.io/specification/#response-object
 class Response(BaseModel):
     description: str
     headers: Optional[Dict[str, Union[Header, Reference]]] = None
@@ -343,6 +365,7 @@ class Config:
             extra = "allow"
 
 
+# https://swagger.io/specification/#operation-object
 class Operation(BaseModel):
     tags: Optional[List[str]] = None
     summary: Optional[str] = None
@@ -367,6 +390,7 @@ class Config:
             extra = "allow"
 
 
+# https://swagger.io/specification/#path-item-object
 class PathItem(BaseModel):
     ref: Optional[str] = Field(default=None, alias="$ref")
     summary: Optional[str] = None
@@ -391,6 +415,7 @@ class Config:
             extra = "allow"
 
 
+# https://swagger.io/specification/#security-scheme-object
 class SecuritySchemeType(Enum):
     apiKey = "apiKey"
     http = "http"
@@ -494,6 +519,7 @@ class OpenIdConnect(SecurityBase):
 SecurityScheme = Union[APIKey, HTTPBase, OAuth2, OpenIdConnect, HTTPBearer]
 
 
+# https://swagger.io/specification/#components-object
 class Components(BaseModel):
     schemas: Optional[Dict[str, Union[Schema, Reference]]] = None
     responses: Optional[Dict[str, Union[Response, Reference]]] = None
@@ -516,6 +542,7 @@ class Config:
             extra = "allow"
 
 
+# https://swagger.io/specification/#tag-object
 class Tag(BaseModel):
     name: str
     description: Optional[str] = None
@@ -530,6 +557,7 @@ class Config:
             extra = "allow"
 
 
+# https://swagger.io/specification/#openapi-object
 class OpenAPI(BaseModel):
     openapi: str
     info: Info