Initial support for OPTIONS method (#127)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: sobolevn <[email protected]>

Author: 3 people

django_modern_rest/__init__.py

@@ -4,6 +4,9 @@
 from django_modern_rest.components import (
     Headers as Headers,
 )
+from django_modern_rest.components import (
+    Path as Path,
+)
 from django_modern_rest.components import (
     Query as Query,
 )
@@ -15,6 +18,12 @@
 from django_modern_rest.endpoint import validate as validate
 from django_modern_rest.headers import HeaderDescription as HeaderDescription
 from django_modern_rest.headers import NewHeader as NewHeader
+from django_modern_rest.meta import (
+    AsyncMetaMixin as AsyncMetaMixin,
+)
+from django_modern_rest.meta import (
+    MetaMixin as MetaMixin,
+)
 from django_modern_rest.response import APIError as APIError
 from django_modern_rest.response import (
     ResponseDescription as ResponseDescription,

django_modern_rest/components.py

@@ -14,6 +14,7 @@
 _QueryT = TypeVar('_QueryT')
 _BodyT = TypeVar('_BodyT')
 _HeadersT = TypeVar('_HeadersT')
+_PathT = TypeVar('_PathT')
 
 
 class ComponentParser:
@@ -159,3 +160,31 @@ def provide_context_data(
         **kwargs: Any,
     ) -> Any:
         return request.headers
+
+
+class Path(ComponentParser, Generic[_PathT]):
+    """
+    Parses the url part of the request.
+
+    # TODO: example
+
+    If your controller class inherits from ``Path`` - then you can access
+    parsed paths parameters as ``self.parsed_path`` attribute.
+
+    It is way stricter than the original Django's routing system.
+    For example, django allows to
+    """
+
+    parsed_path: _PathT
+    context_name: ClassVar[str] = 'parsed_path'
+
+    @override
+    def provide_context_data(
+        self,
+        serializer: type[BaseSerializer],
+        model: Any,
+        request: HttpRequest,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        return kwargs

django_modern_rest/controller.py

@@ -1,4 +1,4 @@
-from http import HTTPStatus
+from http import HTTPMethod, HTTPStatus
 from typing import (
     Any,
     ClassVar,
@@ -83,10 +83,14 @@ class Controller(View, Generic[_SerializerT_co]):  # noqa: WPS214
     controller_validator_cls: ClassVar[type[ControllerValidator]] = (
         ControllerValidator
     )
+    # str and not HTTPMethod, because of `meta` method:
     api_endpoints: ClassVar[dict[str, Endpoint]]
     validate_responses: ClassVar[bool | Empty] = EmptyObj
     responses: ClassVar[list[ResponseDescription]] = []
     responses_from_components: ClassVar[bool] = True
+    http_methods: ClassVar[frozenset[str]] = frozenset(
+        {method.name.lower() for method in HTTPMethod} - {'options'} | {'meta'},
+    )
 
     # Internal API:
     _component_parsers: ClassVar[list[_ComponentParserSpec]]
@@ -116,9 +120,12 @@ def __init_subclass__(cls) -> None:
         ]
         cls.serializer_context = cls.serializer_context_cls(cls)
         cls.api_endpoints = {
-            meth: cls.endpoint_cls(func, controller_cls=cls)
+            # Rename `meta` back to `options`:
+            'options' if meth == 'meta' else meth: cls.endpoint_cls(
+                getattr(cls, meth),
+                controller_cls=cls,
+            )
             for meth in cls.existing_http_methods()
-            if (func := getattr(cls, meth)) is not getattr(View, meth, None)
         }
         cls._is_async = cls.controller_validator_cls()(cls)
 
@@ -218,6 +225,90 @@ def http_method_not_allowed(
             'use `handle_method_not_allowed` instead',
         )
 
+    @override
+    @deprecated(
+        # It is not actually deprecated, but type checkers have no other
+        # ways to raise custom errors.
+        'Please do not use `options` method with `django-modern-rest`, '
+        'define your own `meta` method instead',
+    )
+    def options(
+        self,
+        request: HttpRequest,
+        *args: Any,
+        **kwargs: Any,
+    ) -> HttpResponse:
+        """
+        Do not use, define your own `meta` method instead.
+
+        Django's `View.options` has incompatible signature with
+        ``django-modern-rest``. It would be a typing error
+        to define something like:
+
+        .. warning::
+
+            Don't do this!
+
+            .. code:: python
+
+                >>> from http import HTTPStatus
+                >>> from django_modern_rest import Controller, validate
+                >>> from django_modern_rest.plugins.pydantic import (
+                ...     PydanticSerializer,
+                ... )
+                >>> class MyController(Controller[PydanticSerializer]):
+                ...     @validate(
+                ...         ResponseDescription(
+                ...             None,
+                ...             status_code=HTTPStatus.NO_CONTENT,
+                ...         ),
+                ...     )
+                ...     def options(self) -> HttpResponse:  # <- typing problem
+                ...         ...
+
+        That's why instead of ``options`` you should define
+        our own ``meta`` method:
+
+        .. code:: python
+
+           >>> class MyController(Controller[PydanticSerializer]):
+           ...     @validate(
+           ...         ResponseDescription(
+           ...             None,
+           ...             status_code=HTTPStatus.NO_CONTENT,
+           ...         ),
+           ...     )
+           ...     def meta(self) -> HttpResponse:
+           ...         allow = ','.join(
+           ...             method.upper() for method in self.http_methods
+           ...         )
+           ...         return self.to_response(
+           ...             None,
+           ...             status_code=HTTPStatus.NO_CONTENT,
+           ...             headers={'Allow': allow},
+           ...         )
+
+        .. note::
+
+            By default ``meta`` method is not provided for you.
+            If you want to support ``OPTIONS`` http method
+            with the default implementation, use:
+
+            .. code:: python
+
+               >>> from django_modern_rest import MetaMixin
+
+               >>> class ControllerWithMeta(
+               ...     MetaMixin,
+               ...     Controller[PydanticSerializer],
+               ... ): ...
+
+        """
+        raise NotImplementedError(
+            'Please do not use `options` method with `django-modern-rest`, '
+            'define your own `meta` method instead',
+        )
+
     @classmethod
     def handle_method_not_allowed(
         cls,
@@ -251,7 +342,7 @@ def existing_http_methods(cls) -> set[str]:
         """Returns and caches what HTTP methods are implemented in this view."""
         return {
             method
-            for method in cls.http_method_names
+            for method in cls.http_methods
             if getattr(cls, method, None) is not None
         }
 

django_modern_rest/endpoint.py

@@ -153,7 +153,7 @@ async def decorator(
                 )
             # Return response:
             try:
-                func_result = await func(self._controller, *args, **kwargs)
+                func_result = await func(self._controller)
             except APIError as exc:  # pyright: ignore[reportUnknownVariableType]
                 func_result = self._controller.to_error(
                     exc.raw_data,  # pyright: ignore[reportUnknownMemberType]
@@ -188,7 +188,7 @@ def decorator(
                 )
             # Return response:
             try:
-                func_result = func(self._controller, *args, **kwargs)
+                func_result = func(self._controller)
             except APIError as exc:  # pyright: ignore[reportUnknownVariableType]
                 func_result = self._controller.to_error(
                     exc.raw_data,  # pyright: ignore[reportUnknownMemberType]

django_modern_rest/meta.py

@@ -0,0 +1,92 @@
+from http import HTTPStatus
+from typing import TYPE_CHECKING, Final
+
+from django.http import HttpResponse
+
+from django_modern_rest.endpoint import validate
+from django_modern_rest.headers import HeaderDescription
+from django_modern_rest.response import ResponseDescription
+from django_modern_rest.validation import validate_method_name
+
+if TYPE_CHECKING:
+    from django_modern_rest.controller import Controller
+    from django_modern_rest.serialization import BaseSerializer
+
+
+_OptionsResponse: Final = ResponseDescription(
+    None,
+    status_code=HTTPStatus.NO_CONTENT,
+    headers={'Allow': HeaderDescription()},
+)
+
+
+class MetaMixin:
+    """
+    Mixing that provides default ``meta`` method or ``OPTIONS`` http method.
+
+    Use it for sync controllers.
+
+    It just returns the list of allowed methods.
+    Use it as a mixin with
+    the :class:`django_modern_rest.controller.Controller` type:
+
+    .. code:: python
+
+        >>> from django_modern_rest import Controller, MetaMixin
+        >>> from django_modern_rest.plugins.pydantic import PydanticSerializer
+
+        >>> class SupportsOptionsHttpMethod(
+        ...     MetaMixin,
+        ...     Controller[PydanticSerializer],
+        ... ): ...
+
+    """
+
+    __slots__ = ()
+
+    @validate(_OptionsResponse)
+    def meta(self) -> HttpResponse:
+        """Default sync implementation for ``OPTIONS`` http method."""
+        return _meta_impl(self)  # type: ignore[arg-type]
+
+
+class AsyncMetaMixin:
+    """
+    Mixing that provides default ``meta`` method or ``OPTIONS`` http method.
+
+    Use it for async controllers.
+
+    It just returns the list of allowed methods.
+    Use it as a mixin with
+    the :class:`django_modern_rest.controller.Controller` type:
+
+    .. code:: python
+
+        >>> from django_modern_rest import Controller, AsyncMetaMixin
+        >>> from django_modern_rest.plugins.pydantic import PydanticSerializer
+
+        >>> class SupportsOptionsHttpMethod(
+        ...     AsyncMetaMixin,
+        ...     Controller[PydanticSerializer],
+        ... ): ...
+
+    """
+
+    __slots__ = ()
+
+    @validate(_OptionsResponse)
+    async def meta(self) -> HttpResponse:
+        """Default async implementation for ``OPTIONS`` http method."""
+        return _meta_impl(self)  # type: ignore[arg-type]
+
+
+def _meta_impl(controller: 'Controller[BaseSerializer]') -> HttpResponse:
+    allow = ', '.join(
+        validate_method_name(method).value
+        for method in sorted(controller.existing_http_methods())
+    )
+    return controller.to_response(
+        None,
+        status_code=HTTPStatus.NO_CONTENT,
+        headers={'Allow': allow},
+    )

django_modern_rest/routing.py

@@ -37,6 +37,7 @@ def compose_controllers(
     *extra: type['Controller[_SerializerT]'],
 ) -> type[View]:
     """Combines several controllers with different http methods into one url."""
+    # TODO: validate `meta` composition. Because right now it is not correct.
     controllers = [first_controller, second_controller, *extra]
     is_all_async = _validate_controllers_composition(controllers)
 
@@ -45,6 +46,8 @@ def compose_controllers(
     method_mapping = _build_method_mapping(views)
 
     class ComposedControllerView(View):  # noqa: WPS431
+        original_controllers = controllers
+
         @override
         def dispatch(
             self,
@@ -75,7 +78,6 @@ def _validate_controllers_composition(
     # We know that there are at least 2 controllers as this point:
     is_async = bool(controllers[0].view_is_async)
     serializer = controllers[0].serializer
-
     for controller in controllers:
         if controller.view_is_async is not is_async:
             raise ValueError(
@@ -96,15 +98,13 @@ def _build_method_mapping(
 ) -> Mapping[str, _ViewFunc]:
     method_mapping: dict[str, _ViewFunc] = {}
     for controller, view in views:
-        controller_methods = controller.existing_http_methods() - {'options'}
+        controller_methods = controller.existing_http_methods()
         if not controller_methods:
             raise ValueError(
                 f'Controller {controller} must have at least one endpoint '
                 'to be composed',
             )
         method_intersection = method_mapping.keys() & controller_methods
-        # TODO: decide what to do with default `options` method.
-        # Do we need it? Maybe it should be removed?
         if method_intersection:
             raise ValueError(
                 f'Controllers have {method_intersection!r} common methods, '

django_modern_rest/validation.py

@@ -232,6 +232,8 @@ class ControllerValidator:
 
     def __call__(self, controller: 'type[Controller[BaseSerializer]]') -> bool:
         """Run the validation."""
+        # TODO: validate that sync controller have `MetaMixin`
+        # and async ones have `AsyncMetaMixin`
         self._validate_components(controller)
         return self._validate_endpoints(controller)
 
@@ -395,6 +397,7 @@ def __call__(
         """Do the validation."""
         return_annotation = parse_return_annotation(func)
         method = validate_method_name(func.__name__)
+        func.__name__ = str(method).lower()  # we can change it :)
         endpoint = str(func)
         # TODO: validate contoller's definition.
         # Questions: how? when? one time?
@@ -611,6 +614,8 @@ def validate_method_name(func_name: str) -> HTTPMethod:
     try:  # noqa: WPS229
         if func_name != func_name.lower():
             raise ValueError  # noqa: TRY301
+        if func_name == 'meta':
+            return HTTPMethod.OPTIONS
         return HTTPMethod(func_name.upper())
     except ValueError:
         raise EndpointMetadataError(