starmallow 0.8.0__py3-none-any.whl → 0.9.0__py3-none-any.whl

starmallow/schema_generator.py

@@ -4,14 +4,14 @@ import itertools
 import re
 import warnings
 from collections import defaultdict
+from collections.abc import Generator, Mapping
 from logging import getLogger
-from typing import Any, Dict, Generator, List, Optional, Sequence, Set, Tuple, Type
+from typing import Any, cast
 
 import marshmallow as ma
 import marshmallow.fields as mf
 from apispec import APISpec
-from apispec.ext.marshmallow import OpenAPIConverter, SchemaResolver
-# from apispec.ext.marshmallow.openapi import OpenAPIConverter
+from apispec.ext.marshmallow import OpenAPIConverter, SchemaResolver  # type: ignore
 from starlette.responses import Response
 from starlette.routing import BaseRoute, Mount, compile_path
 from starlette.schemas import BaseSchemaGenerator
@@ -26,16 +26,17 @@ from starmallow.security.base import SecurityBaseResolver
 from starmallow.utils import (
     deep_dict_update,
     dict_safe_add,
-    is_marshmallow_field,
     status_code_ranges,
 )
 
 logger = getLogger(__name__)
 
+
 class SchemaRegistry(dict):
     '''
         Dict that holds all the schemas for each class and lazily resolves them.
     '''
+
     def __init__(
         self,
         spec: APISpec,
@@ -59,7 +60,7 @@ class SchemaRegistry(dict):
             sec_obj = self.security_references.__getitem__(component_id)
         except KeyError:
             # Use marshmallow_dataclass to dump itself
-            sec_schema = model.Schema().dump(model)
+            sec_schema = cast(dict, model.Schema().dump(model))
             sec_schema['type'] = model.type.value
 
             self.spec.components.security_scheme(component_id=component_id, component=sec_schema)
@@ -74,7 +75,7 @@ class SchemaRegistry(dict):
         if isinstance(item, SecurityBaseResolver):
             return self._get_security_item(item)
 
-        if is_marshmallow_field(item):
+        if isinstance(item, mf.Field):
             # If marshmallow field, just resolve it here without caching
             prop = self.converter.field2property(item)
             return prop
@@ -92,7 +93,9 @@ class SchemaRegistry(dict):
             try:
                 schema = self.spec.components.schemas.__getitem__(component_id)
             except KeyError:
-                self.spec.components.schema(component_id=component_id, schema=item)
+                self.spec.components.schema(
+                    component_id=component_id, schema=item,
+                )
 
             schema = self.resolver.resolve_schema_dict(item)
             super().__setitem__(schema_class, schema)
@@ -124,19 +127,24 @@ class SchemaGenerator(BaseSchemaGenerator):
             plugins=[marshmallow_plugin],
         )
 
+        if marshmallow_plugin.converter is None or marshmallow_plugin.resolver is None:
+            raise ValueError(
+                "Converter and resolver must be initialized before use.",
+            )
+
         self.converter = marshmallow_plugin.converter
         self.resolver = marshmallow_plugin.resolver
 
         # Builtin definitions
         self.schemas = SchemaRegistry(self.spec, self.converter, self.resolver)
 
-        self.operation_ids: Set[str] = set()
+        self.operation_ids: set[str] = set()
 
-    def get_endpoints(
+    def get_endpoints( # type: ignore
         self,
-        routes: List[BaseRoute],
+        routes: list[BaseRoute],
         base_path: str = "",
-    ) -> Dict[str, Sequence[EndpointModel]]:
+    ) -> dict[str, list[EndpointModel]]:
         """
             Given the routes, yields the following information:
 
@@ -151,11 +159,11 @@ class SchemaGenerator(BaseSchemaGenerator):
             This allows each path to have multiple responses.
         """
 
-        endpoints_info: Dict[str, Sequence[APIRoute]] = defaultdict(list)
+        endpoints_info: dict[str, list[EndpointModel]] = defaultdict(list)
 
         for route in routes:
             # path is not defined in BaseRoute, but all implementations have it.
-            _, path, _ = compile_path(base_path + route.path)
+            _, path, _ = compile_path(base_path + route.path)  # type: ignore
 
             if isinstance(route, APIRoute) and route.include_in_schema:
                 if inspect.isfunction(route.endpoint) or inspect.ismethod(route.endpoint):
@@ -166,12 +174,16 @@ class SchemaGenerator(BaseSchemaGenerator):
                         endpoints_info[path].append(route.endpoint_model)
 
             elif isinstance(route, Mount):
-                endpoints_info.update(self.get_endpoints(route.routes, base_path=path))
+                endpoints_info.update(
+                    self.get_endpoints(
+                    route.routes, base_path=path,
+                    ),
+                )
 
         return endpoints_info
 
-    def _to_parameters(self, *params: Dict[str, Query | Path | Header | Cookie]) -> Generator[Dict[str, Any], None, None]:
-        for name, field in itertools.chain(*(p.items() for p in params)):
+    def _to_parameters(self, *params: Mapping[str, Query | Path | Header | Cookie] | None) -> Generator[dict[str, Any], None, None]:
+        for name, field in itertools.chain(*(p.items() for p in params if p is not None)):
             if not field.include_in_schema:
                 continue
 
@@ -183,9 +195,13 @@ class SchemaGenerator(BaseSchemaGenerator):
                         location=field.in_.name,
                     )
 
-            else:
+            elif field.model is not None:
                 yield self.converter._field2parameter(
-                    field.model,
+                    (
+                        field.model
+                        if isinstance(field.model, mf.Field)
+                        else mf.Nested(field.model)
+                    ),
                     name=name,
                     location=field.in_.name,
                 )
@@ -193,7 +209,7 @@ class SchemaGenerator(BaseSchemaGenerator):
     def _add_endpoint_parameters(
         self,
         endpoint: EndpointModel,
-        schema: Dict,
+        schema: dict,
     ):
         unique_params = {}
         for param in self._to_parameters(
@@ -207,7 +223,9 @@ class SchemaGenerator(BaseSchemaGenerator):
                     # Duplicate parameter, skip. Could be defined as a field and in a schema.
                     continue
                 else:
-                    raise ValueError(f"Duplicate parameter with name {param['name']} and location {param['in']}")
+                    raise ValueError(
+                        f"Duplicate parameter with name {param['name']} and location {param['in']}",
+                    )
 
             unique_params[param['name']] = param
 
@@ -216,11 +234,14 @@ class SchemaGenerator(BaseSchemaGenerator):
     def _add_endpoint_body(
         self,
         endpoint: EndpointModel,
-        schema: Dict,
+        schema: dict,
     ):
-        all_body_params: List[Tuple[str, Body]] = [
-            *endpoint.body_params.items(),
-            *endpoint.form_params.items(),
+        if not isinstance(endpoint.route, APIRoute):
+            return
+
+        all_body_params: list[tuple[str, Body]] = [
+            *(endpoint.body_params.items() if endpoint.body_params else []),
+            *(endpoint.form_params.items() if endpoint.form_params else []),
         ]
         schema_by_media_type = {}
         is_body_required = True
@@ -231,8 +252,8 @@ class SchemaGenerator(BaseSchemaGenerator):
             if body_param.include_in_schema:
                 endpoint_schema = self.schemas[body_param.model]
 
-            if endpoint_schema:
-                schema_by_media_type[body_param.media_type] = {'schema': endpoint_schema}
+                if endpoint_schema:
+                    schema_by_media_type[body_param.media_type] = {'schema': endpoint_schema}
 
             if getattr(body_param.model, 'required', True) is False:
                 is_body_required = False
@@ -254,8 +275,11 @@ class SchemaGenerator(BaseSchemaGenerator):
             component_by_media_type = defaultdict(new_endpoint_schema)
             for name, value in all_body_params:
                 media_component = component_by_media_type[value.media_type]
-                endpoint_properties: Dict[str, Any] = media_component['properties']
-                required_properties: List[Any] = media_component['required']
+                endpoint_properties: dict[
+                    str,
+                    Any,
+                ] = media_component['properties']
+                required_properties: list[Any] = media_component['required']
 
                 if value.include_in_schema:
                     if isinstance(value.model, ma.Schema):
@@ -264,7 +288,9 @@ class SchemaGenerator(BaseSchemaGenerator):
                             required_properties.append(name)
 
                     elif isinstance(value.model, mf.Field):
-                        endpoint_properties[name] = self.converter.field2property(value.model)
+                        endpoint_properties[name] = self.converter.field2property(
+                            value.model,
+                        )
                         if value.model.required:
                             required_properties.append(name)
 
@@ -273,7 +299,9 @@ class SchemaGenerator(BaseSchemaGenerator):
 
             schema_by_media_type = {}
             for media_type, component in component_by_media_type.items():
-                self.spec.components.schema(component_id=component_schema_id, component=component)
+                self.spec.components.schema(
+                    component_id=component_schema_id, component=component,
+                )
 
                 schema_by_media_type[media_type] = {
                     "schema": {
@@ -290,21 +318,26 @@ class SchemaGenerator(BaseSchemaGenerator):
     def _add_security_params(
         self,
         endpoint: EndpointModel,
-        schema: Dict,
+        schema: dict,
     ):
-        schema['security'] = [
-            self.schemas[security_param.resolver]
-            for param_name, security_param in endpoint.security_params.items()
-        ]
+        if endpoint.security_params:
+            schema['security'] = [
+                self.schemas[security_param.resolver]
+                for param_name, security_param in endpoint.security_params.items()
+            ]
 
     def _add_endpoint_response(
         self,
         endpoint: EndpointModel,
-        schema: Dict,
+        schema: dict,
     ):
         operation_responses = schema.setdefault("responses", {})
         response_codes = list(operation_responses.keys())
-        main_response = str(endpoint.status_code or (response_codes[0] if response_codes else 200))
+        main_response = str(
+            endpoint.status_code or (
+            response_codes[0] if response_codes else 200
+            ),
+        )
 
         operation_responses[main_response] = {
             'content': {
@@ -313,17 +346,20 @@ class SchemaGenerator(BaseSchemaGenerator):
                 },
             },
         }
+        if not isinstance(endpoint.route, APIRoute):
+            return
+
         if endpoint.route.response_description:
             operation_responses[main_response]['description'] = endpoint.route.response_description
 
         # Process additional responses
         route = endpoint.route
         if isinstance(route.response_class, DefaultPlaceholder):
-            current_response_class: Type[Response] = route.response_class.value
+            current_response_class: type[Response] = route.response_class.value
         else:
             current_response_class = route.response_class
         assert current_response_class, "A response class is needed to generate OpenAPI"
-        route_response_media_type: Optional[str] = current_response_class.media_type
+        route_response_media_type: str | None = current_response_class.media_type
 
         if route.responses:
             for (
@@ -342,17 +378,21 @@ class SchemaGenerator(BaseSchemaGenerator):
                     status_code_key, {},
                 )
                 field = route.response_fields.get(additional_status_code)
-                additional_field_schema: Optional[Dict[str, Any]] = None
+                additional_field_schema: dict[str, Any] | None = None
                 if field:
-                    additional_field_schema = self.schemas[field] if field else {}
+                    additional_field_schema = self.schemas[field] if field else {
+                    }
                     media_type = route_response_media_type or "application/json"
                     additional_schema = (
                         process_response.setdefault("content", {})
                         .setdefault(media_type, {})
                         .setdefault("schema", {})
                     )
-                    deep_dict_update(additional_schema, additional_field_schema)
-                status_text: Optional[str] = status_code_ranges.get(
+                    deep_dict_update(
+                        additional_schema,
+                        additional_field_schema,
+                    )
+                status_text: str | None = status_code_ranges.get(
                     str(additional_status_code).upper(),
                 ) or http.client.responses.get(int(additional_status_code))
                 description = (
@@ -364,7 +404,7 @@ class SchemaGenerator(BaseSchemaGenerator):
                 deep_dict_update(openapi_response, process_response)
                 openapi_response["description"] = description
 
-    def _add_default_error_response(self, schema: Dict):
+    def _add_default_error_response(self, schema: dict):
         dict_safe_add(
             schema,
             'responses.422.description',
@@ -381,7 +421,7 @@ class SchemaGenerator(BaseSchemaGenerator):
             return route.summary
         return re.sub(r"(\w)([A-Z])", r"\1 \2", route.name).replace(".", " ").replace("_", " ").title()
 
-    def _get_route_openapi_metadata(self, route: APIRoute) -> Dict[str, Any]:
+    def _get_route_openapi_metadata(self, route: APIRoute) -> dict[str, Any]:
         schema = {}
         if route.tags:
             schema["tags"] = route.tags
@@ -391,10 +431,11 @@ class SchemaGenerator(BaseSchemaGenerator):
         operation_id = route.operation_id or route.unique_id
         if operation_id in self.operation_ids:
             message = (
-                f"Duplicate Operation ID {operation_id} for function "
-                + f"{route.endpoint.__name__}"
+                f"Duplicate Operation ID {operation_id} for function {route.endpoint.__name__}"
             )
-            file_name = getattr(route.endpoint, "__globals__", {}).get("__file__")
+            file_name = getattr(
+                route.endpoint, "__globals__", {},
+            ).get("__file__")
             if file_name:
                 message += f" at {file_name}"
             warnings.warn(message)
@@ -408,10 +449,14 @@ class SchemaGenerator(BaseSchemaGenerator):
     def get_endpoint_schema(
         self,
         endpoint: EndpointModel,
-    ) -> Dict[str, Any]:
+    ) -> dict[str, Any]:
         '''
             Generates the endpoint schema
         '''
+
+        if not isinstance(endpoint.route, APIRoute):
+            return {}
+
         schema = self._get_route_openapi_metadata(endpoint.route)
 
         schema.update(self.parse_docstring(endpoint.call))
@@ -458,18 +503,19 @@ class SchemaGenerator(BaseSchemaGenerator):
 
         return schema
 
-    def get_operations(self, endpoints: List[EndpointModel]):
+    def get_operations(self, endpoints: list[EndpointModel]) -> dict[str, dict[str, Any]]:
         return {
             method.lower(): self.get_endpoint_schema(e)
             for e in endpoints
+            if e.methods
             for method in e.methods
             if method != 'HEAD'
         }
 
     def get_schema(
         self,
-        routes: List[APIRoute],
-    ) -> Dict[str, Any]:
+        routes: list[BaseRoute],
+    ) -> dict[str, Any]:
         '''
             Generates the schemas for the specified routes..
         '''

starmallow/security/api_key.py

@@ -1,5 +1,5 @@
 from enum import Enum
-from typing import ClassVar, Optional
+from typing import ClassVar
 
 from marshmallow_dataclass2 import dataclass as ma_dataclass
 from starlette.requests import Request
@@ -28,15 +28,15 @@ class APIKeyQuery(SecurityBaseResolver):
         self,
         *,
         name: str,
-        scheme_name: Optional[str] = None,
-        description: Optional[str] = None,
+        scheme_name: str | None = None,
+        description: str | None = None,
         auto_error: bool = True,
     ):
         self.model: APIKeyModel = APIKeyModel(in_=APIKeyIn.query, name=name, description=description)
         self.scheme_name = scheme_name or self.__class__.__name__
         self.auto_error = auto_error
 
-    async def __call__(self, request: Request) -> Optional[str]:
+    async def __call__(self, request: Request) -> str | None:
         api_key = request.query_params.get(self.model.name)
         if not api_key:
             if self.auto_error:
@@ -53,15 +53,15 @@ class APIKeyHeader(SecurityBaseResolver):
         self,
         *,
         name: str,
-        scheme_name: Optional[str] = None,
-        description: Optional[str] = None,
+        scheme_name: str | None = None,
+        description: str | None = None,
         auto_error: bool = True,
     ):
         self.model: APIKeyModel = APIKeyModel(in_=APIKeyIn.header, name=name, description=description)
         self.scheme_name = scheme_name or self.__class__.__name__
         self.auto_error = auto_error
 
-    async def __call__(self, request: Request) -> Optional[str]:
+    async def __call__(self, request: Request) -> str | None:
         api_key = request.headers.get(self.model.name)
         if not api_key:
             if self.auto_error:
@@ -78,15 +78,15 @@ class APIKeyCookie(SecurityBaseResolver):
         self,
         *,
         name: str,
-        scheme_name: Optional[str] = None,
-        description: Optional[str] = None,
+        scheme_name: str | None = None,
+        description: str | None = None,
         auto_error: bool = True,
     ):
         self.model: APIKeyModel = APIKeyModel(in_=APIKeyIn.cookie, name=name, description=description)
         self.scheme_name = scheme_name or self.__class__.__name__
         self.auto_error = auto_error
 
-    async def __call__(self, request: Request) -> Optional[str]:
+    async def __call__(self, request: Request) -> str | None:
         api_key = request.cookies.get(self.model.name)
         if not api_key:
             if self.auto_error:

starmallow/security/base.py

@@ -1,8 +1,9 @@
 from enum import Enum
-from typing import Any, ClassVar, Dict, Optional
+from typing import Any, ClassVar
 
 import marshmallow as ma
 from marshmallow_dataclass2 import dataclass as ma_dataclass
+from starlette.requests import Request
 
 
 # Provided by: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.1.0.md#security-scheme-object
@@ -16,11 +17,13 @@ class SecurityTypes(Enum):
 
 @ma_dataclass(frozen=True)
 class SecurityBase:
+    Schema: ClassVar[type[ma.Schema]]
+
     type: ClassVar[SecurityTypes]
-    description: Optional[str] = None
+    description: str | None = None
 
     @ma.post_dump()
-    def post_dump(self, data: Dict[str, Any], **kwargs):
+    def post_dump(self, data: dict[str, Any], **kwargs):
         # Remove None values
         return {
             key: value
@@ -40,3 +43,8 @@ class SecurityBaseResolver:
     ) -> None:
         self.model = model
         self.schema_name = scheme_name
+
+    async def __call__(self, request: Request) -> Any | None:
+        raise NotImplementedError(
+            f"SecurityBaseResolver.__call__ not implemented for {self.__class__.__name__}",
+        )

starmallow/security/http.py

@@ -1,6 +1,7 @@
+import asyncio
 import binascii
 from base64 import b64decode
-from typing import ClassVar, Optional
+from typing import ClassVar
 
 from marshmallow_dataclass2 import dataclass as ma_dataclass
 from starlette.requests import Request
@@ -33,14 +34,14 @@ class HTTPAuthorizationCredentials:
 @ma_dataclass(frozen=True)
 class HTTPBaseModel(SecurityBase):
     type: ClassVar[SecurityTypes] = SecurityTypes.http
-    description: Optional[str] = None
-    scheme: str = None
+    description: str | None = None
+    scheme: str | None = None
 
 
 @ma_dataclass(frozen=True)
 class HTTPBearerModel(HTTPBaseModel):
     scheme: str = "bearer"
-    bearerFormat: Optional[str] = None
+    bearer_format: str | None = None
 
 
 class HTTPBase(SecurityBaseResolver):
@@ -49,8 +50,8 @@ class HTTPBase(SecurityBaseResolver):
         self,
         *,
         scheme: str,
-        scheme_name: Optional[str] = None,
-        description: Optional[str] = None,
+        scheme_name: str | None = None,
+        description: str | None = None,
         auto_error: bool = True,
     ) -> None:
         self.model = HTTPBaseModel(scheme=scheme, description=description)
@@ -59,7 +60,7 @@ class HTTPBase(SecurityBaseResolver):
 
     async def __call__(
         self, request: Request,
-    ) -> Optional[HTTPAuthorizationCredentials]:
+    ) -> HTTPAuthorizationCredentials | None:
         authorization = request.headers.get("Authorization")
         scheme, credentials = get_authorization_scheme_param(authorization)
         if not (authorization and scheme and credentials):
@@ -77,9 +78,9 @@ class HTTPBasic(HTTPBase):
     def __init__(
         self,
         *,
-        scheme_name: Optional[str] = None,
-        realm: Optional[str] = None,
-        description: Optional[str] = None,
+        scheme_name: str | None = None,
+        realm: str | None = None,
+        description: str | None = None,
         auto_error: bool = True,
     ) -> None:
         super().__init__(
@@ -93,13 +94,14 @@ class HTTPBasic(HTTPBase):
 
     async def __call__(  # type: ignore
         self, request: Request,
-    ) -> Optional[HTTPBasicCredentials]:
+    ) -> HTTPBasicCredentials | None:
         authorization = request.headers.get("Authorization")
         scheme, param = get_authorization_scheme_param(authorization)
-        if self.realm:
-            unauthorized_headers = {"WWW-Authenticate": f'Basic realm="{self.realm}"'}
-        else:
-            unauthorized_headers = {"WWW-Authenticate": "Basic"}
+        unauthorized_headers = (
+            {"WWW-Authenticate": f'Basic realm="{self.realm}"'}
+            if self.realm
+            else {"WWW-Authenticate": "Basic"}
+        )
         invalid_user_credentials_exc = HTTPException(
             status_code=HTTP_401_UNAUTHORIZED,
             detail="Invalid authentication credentials",
@@ -115,9 +117,12 @@ class HTTPBasic(HTTPBase):
             else:
                 return None
         try:
-            data = b64decode(param).decode("ascii")
+            def decode(param: str) -> str:
+                return b64decode(param).decode("ascii")
+
+            data = await asyncio.to_thread(decode, param)
         except (ValueError, UnicodeDecodeError, binascii.Error):
-            raise invalid_user_credentials_exc
+            raise invalid_user_credentials_exc from None
         username, separator, password = data.partition(":")
         if not separator:
             raise invalid_user_credentials_exc
@@ -129,18 +134,18 @@ class HTTPBearer(HTTPBase):
     def __init__(
         self,
         *,
-        bearerFormat: Optional[str] = None,
-        scheme_name: Optional[str] = None,
-        description: Optional[str] = None,
+        bearer_format: str | None = None,
+        scheme_name: str | None = None,
+        description: str | None = None,
         auto_error: bool = True,
     ) -> None:
-        self.model = HTTPBearerModel(bearerFormat=bearerFormat, description=description)
+        self.model = HTTPBearerModel(bearer_format=bearer_format, description=description)
         self.scheme_name = scheme_name or self.__class__.__name__
         self.auto_error = auto_error
 
     async def __call__(
         self, request: Request,
-    ) -> Optional[HTTPAuthorizationCredentials]:
+    ) -> HTTPAuthorizationCredentials | None:
         authorization = request.headers.get("Authorization")
         scheme, credentials = get_authorization_scheme_param(authorization)
         if not (authorization and scheme and credentials):
@@ -166,8 +171,8 @@ class HTTPDigest(HTTPBase):
     def __init__(
         self,
         *,
-        scheme_name: Optional[str] = None,
-        description: Optional[str] = None,
+        scheme_name: str | None = None,
+        description: str | None = None,
         auto_error: bool = True,
     ) -> None:
         super().__init__(
@@ -179,7 +184,7 @@ class HTTPDigest(HTTPBase):
 
     async def __call__(
         self, request: Request,
-    ) -> Optional[HTTPAuthorizationCredentials]:
+    ) -> HTTPAuthorizationCredentials | None:
         authorization = request.headers.get("Authorization")
         scheme, credentials = get_authorization_scheme_param(authorization)
         if not (authorization and scheme and credentials):