Public API

Controller

class dmr.controller.Controller(**kwargs)

Bases: View, Generic[_SerializerT_co]

Defines API views as controllers.

Controller is a django.views.generic.base.View subclass that should be used as a base for all REST endpoints.

endpoint_cls

Class to create endpoints with.

Type:

ClassVar[type[dmr.endpoint.Endpoint]]

serializer

Serializer that is passed via type parameters. The main goal of the serializer is to serialize object to json and deserialize them from json. You can’t change the serializer simply by modifying the attribute in the controller class. Because it is already passed to many other places. To customize it: create a new class, subclass BaseSerializer, and pass the new type as a type argument to the controller.

Type:

ClassVar[type[dmr.serializer.BaseSerializer]]

settings_validator_cls

Runs settings validation once the first controller is created.

Type:

ClassVar[type[dmr.validation.settings.SettingsValidator]]

no_validate_http_spec

Set of http spec validation checks that we disable for this class.

Type:

ClassVar[collections.abc.Set[dmr.settings.HttpSpec] | None]

validate_responses

Boolean whether or not validating responses. Works in runtime, can be disabled for better performance.

Type:

ClassVar[bool | None]

exclude_validate_responses

Set of status codes that we don’t validate, even when validate_responses is enabled. Useful for errors like 500 that can be raised from anywhere and that you might not want to describe.

Type:

ClassVar[collections.abc.Set[http.HTTPStatus] | None]

semantic_responses

Should semantic responses be collected from different providers for all endpoints in this class.

Type:

ClassVar[bool | None]

exclude_semantic_responses

Set of semantic responses that user wants to disable.

Type:

ClassVar[collections.abc.Set[http.HTTPStatus] | None]

validate_events

Should this endpoint validate events? If not set, defaults to the validate_responses value. This value only matters if the response will be a streaming response that supports event validation.

Type:

ClassVar[bool | None]

responses

List of responses schemas that this controller can return. Also customizable in endpoints and globally with 'responses' key in the settings.

Type:

ClassVar[collections.abc.Sequence[dmr.metadata.ResponseSpec]]

allowed_http_methods

Set of names to be treated as names for endpoints. Does not include options, but includes meta.

Type:

ClassVar[collections.abc.Set[str]]

parsers

Sequence of parsers to be used for this controller to parse incoming request’s body. All instances must be of subtypes of Parser.

Type:

ClassVar[collections.abc.Sequence[dmr.parsers.Parser]]

renderers

Sequence of renderers to be used for this controller to render response’s body. All instances must be of subtypes of Renderer.

Type:

ClassVar[collections.abc.Sequence[dmr.renderers.Renderer]]

validate_negotiation

Should we validate that returned response’s Content-Type header matches the one that we inferred in the negotiation process?

Type:

ClassVar[bool | None]

auth

Sequence of auth instances to be used for this controller. Sync controllers must use instances of dmr.security.SyncAuth. Async controllers must use instances of dmr.security.AsyncAuth. Set it to None to disable auth of this controller.

Type:

ClassVar[collections.abc.Sequence[dmr.security.base.SyncAuth] | collections.abc.Sequence[dmr.security.base.AsyncAuth] | None]

throttling

Sequence of throttle instances to be used. Sync controllers must use instances of dmr.throttling.SyncThrottle. Async controllers must use instances of dmr.throttling.AsyncThrottle. Set it to None to disable throttling of this controller.

Type:

ClassVar[collections.abc.Sequence[dmr.throttling.base.SyncThrottle] | collections.abc.Sequence[dmr.throttling.base.AsyncThrottle] | None]

throttling_allow_unsafe_cache

Should this controller allow unsafe throttle Django cache backends?

Type:

ClassVar[bool | typing_extensions.sentinel | None]

error_model

Schema type that represents and validates common error responses.

Type:

ClassVar[Any]

is_abstract

Whether or not this controller is abstract. We consider controller “abstract” when it does not have exact serializer type or exact api_endpoints instances.

Type:

ClassVar[bool]

is_async

Whether or not this controller is async.

Type:

ClassVar[bool | None]

streaming

Does this controller work with streaming responses like SSE?

Type:

ClassVar[bool]

controller_validator_cls

Runs full controller validation on definition.

Type:

ClassVar[type[dmr.validation.controller.ControllerValidator]]

annotations_context

Inference context to call typing.get_type_hints() for this controller.

Type:

ClassVar[dmr.types.AnnotationsContext]

api_endpoints

Dictionary of HTTPMethod name to controller instance.

Type:

ClassVar[collections.abc.Mapping[str, dmr.endpoint.Endpoint]]

csrf_exempt

Should this controller be exempted from the CSRF check? Is True by default.

Type:

ClassVar[bool]

summary

A short summary of what this path item does.

Type:

ClassVar[_StrOrPromise | None]

description

A verbose explanation of the path item behavior.

Type:

ClassVar[_StrOrPromise | None]

servers

An alternative servers array to service this path item.

Type:

ClassVar[collections.abc.Sequence[dmr.openapi.objects.server.Server] | None]

ignore_from_spec

If set to True, all endpoints from this controller would not be added to the final OpenAPI spec.

Type:

ClassVar[bool]

request

Current HttpRequest instance.

args

Path positional parameters of the request.

kwargs

Path named parameters of the request.

Type:

dict[str, Any]

classmethod __init_subclass__() → None

Construct a controller.

classmethod as_view(**initkwargs: Any) → Callable[[...], HttpResponseBase]

Returns a view function for the class-based view.

This override applies CSRF exemption to the view. Session-based authentication will still be explicitly validated for CSRF, while all other authentication methods will be CSRF-exempt.

dispatch(request: HttpRequest, *args: Any, **kwargs: Any) → HttpResponseBase

Find an endpoint that serves this HTTP method and call it.

Return 405 if this method is not allowed.

format_error(error: str | Exception, *, loc: str | list[str | int] | None = None, error_type: str | ErrorType | None = None) → Any

Convert error to the common format.

Parameters:

• error – A serialization exception like a validation error.

• loc – Location where this error happened. Like "headers", or "field_name", or ["parsed_headers", "header_name"].

• error_type – Optional type of the error for extra metadata.

Returns:

Simple python object - exception converted to a common format.

classmethod get_schema(path: str, pattern: URLPattern, context: OpenAPIContext, router: Router) → PathItem | None

Generate OpenAPI spec for path items.

Changed in version 0.13.0:

• Renamed from get_path_item to get_schema

• Now allows to return None to ignore whole path items from OpenAPI schema

async handle_async_error(endpoint: Endpoint, controller: Controller[_SerializerT_co], exc: Exception) → HttpResponse

Return error response if possible. Async case.

Override this method to add custom error handling for async execution. By default - does nothing, only re-raises the passed error. Won’t be called when using sync endpoints.

handle_error(endpoint: Endpoint, controller: Controller[_SerializerT_co], exc: Exception) → HttpResponse

Return error response if possible. Sync case.

Override this method to add custom error handling for sync execution. By default - does nothing, only re-raises the passed error. Won’t be called when using async endpoints.

handle_method_not_allowed(method: str) → HttpResponse

Return error response for 405 response code.

It is special in way that we don’t have an endpoint associated with it.

http_method_not_allowed(request: HttpRequest, *args: Any, **kwargs: Any) → HttpResponse

Do not use, use handle_method_not_allowed() instead.

View.http_method_not_allowed raises an error in a wrong format.

options(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!

>>> from http import HTTPStatus
>>> from dmr import Controller, validate
>>> from dmr.plugins.pydantic import (
...     PydanticSerializer,
... )
>>> class MyController(Controller[PydanticSerializer]):
...     @validate(
...         ResponseSpec(
...             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:

>>> class MyController(Controller[PydanticSerializer]):
...     @validate(
...         ResponseSpec(
...             None,
...             status_code=HTTPStatus.NO_CONTENT,
...         ),
...     )
...     def meta(self) -> HttpResponse:
...         allow = ','.join(
...             method.upper()
...             for method in self.allowed_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:

>>> from dmr.options_mixins import MetaMixin

>>> class ControllerWithMeta(
...     MetaMixin,
...     Controller[PydanticSerializer],
... ): ...

setup(request: HttpRequest, *args: Any, **kwargs: Any) → None

Set request context.

Unlike setup() does not set head method automatically.

Thread safety: there’s only one controller instance per request.

to_error(raw_data: Any, *, status_code: HTTPStatus, headers: Mapping[str, str] | None = None, cookies: Mapping[str, NewCookie] | None = None, renderer: Renderer | None = None) → HttpResponse

Helpful method to convert API error parts into an actual error.

Always requires the error code to be passed. Is an alias for to_response method with a siglightly different signature and semantics.

Should be always used instead of using raw django.http.HttpResponse objects. Does the usual validation, no “second validation” problem exists.

to_response(raw_data: Any, *, status_code: HTTPStatus | None = None, headers: Mapping[str, str] | None = None, cookies: Mapping[str, NewCookie] | None = None, renderer: Renderer | None = None) → HttpResponse

Helpful method to convert response parts into an actual response.

Should be always used instead of using raw django.http.HttpResponse objects. Has better serialization speed and semantics than manual. Does the usual validation, no “second validation” problem exists.

Endpoint

class dmr.endpoint.Endpoint(func: Callable[[...], Any], *, controller_cls: type[Controller[BaseSerializer]])

Represents the single API endpoint.

Is built during the import time. In the runtime only does response validate, which can be disabled.

__call__(controller: Controller[BaseSerializer], *args: Any, **kwargs: Any) → HttpResponseBase

Run the endpoint and return the response.

get_operation_id(path: str, controller_name: str, serializer: type[BaseSerializer], context: OpenAPIContext) → str

Customize how OperationId is generated for the OpenAPI.

get_schema(path: str, pattern: URLPattern, controller_name: str, serializer: type[BaseSerializer], context: OpenAPIContext, router: Router) → Operation

Build an OpenAPI Operation from an endpoint.

async handle_async_error(controller: Controller[BaseSerializer], exc: Exception) → HttpResponse

Return error response if possible.

Override this method to add custom async error handling.

handle_error(controller: Controller[BaseSerializer], exc: Exception) → HttpResponseBase

Return error response if possible.

Override this method to add custom error handling.

metadata_builder_cls

alias of EndpointMetadataBuilder

metadata_cls

alias of EndpointMetadata

metadata_validator_cls

alias of EndpointMetadataValidator

request_negotiator_cls

alias of RequestNegotiator

response_modification_cls

alias of ResponseModification

response_negotiator_cls

alias of ResponseNegotiator

response_validator_cls

alias of ResponseValidator

serializer_context_cls

alias of SerializerContext

class dmr.metadata.EndpointMetadata(*, endpoint_name: str, type_annotations: dict[str, Any], responses: dict[HTTPStatus, ResponseSpec], validate_responses: bool, method: str, modification: ResponseModification | None, error_handler: SyncErrorHandler | AsyncErrorHandler | None, component_parsers: list[tuple[ComponentParser, Any, tuple[Any, ...]]], parsers: dict[str, Parser], renderers: dict[str, Renderer], validate_negotiation: bool, auth: list[SyncAuth | AsyncAuth] | None, throttling_before_auth: tuple[SyncThrottle | AsyncThrottle, ...] | None, throttling_after_auth: tuple[SyncThrottle | AsyncThrottle, ...] | None, throttling_allow_unsafe_cache: bool | None, exclude_validate_responses: frozenset[HTTPStatus], no_validate_http_spec: frozenset[HttpSpec], allowed_http_methods: frozenset[str], semantic_responses: bool, exclude_semantic_responses: frozenset[HTTPStatus], validate_events: bool, summary: _StrOrPromise | None, description: _StrOrPromise | None, tags: list[str] | None, operation_id: str | None, deprecated: bool, external_docs: ExternalDocumentation | None, callbacks: dict[str, Callback | Reference] | None, servers: list[Server] | None, ignore_from_spec: bool)

Base class for common endpoint metadata.

endpoint_name

Text representation of an endpoint name for better error messages.

Type:

str

type_annotations

Unmodified unnotations of the endpoint function, returned by the resolution method.

Type:

dict[str, Any]

responses

Mapping of HTTP method to response description. All possible responses that this API can return. Used for OpenAPI spec generation and for response validation.

Type:

dict[http.HTTPStatus, dmr.metadata.ResponseSpec]

method

String name of an HTTP method for this endpoint.

Type:

str

validate_responses

Do we have to run runtime validation of responses for this endpoint? Already resolved from the global setting, the controller, and the endpoint.

Type:

bool

modification

Default modifications that are applied to the returned data. Can be None, when @validate is used.

Type:

dmr.metadata.ResponseModification | None

error_handler

Callback function to be called when this endpoint faces an exception.

Type:

SyncErrorHandler | AsyncErrorHandler | None

component_parsers

List of component parser specifications from the controller. Each spec is a tuple of (ComponentParser class, type args).

Type:

list[tuple[ComponentParser, Any, tuple[Any, …]]]

parsers

List of instances to be used for this endpoint to parse incoming request’s body. All instances must be of subtypes of Parser.

Type:

dict[str, Parser]

renderers

List of instances to be used for this endpoint to render response’s body. All instances must be of subtypes of Renderer.

Type:

dict[str, Renderer]

validate_negotiation

Should we validate that returned response’s Content-Type header matches the one that we inferred in the negotiation process?

Type:

bool

auth

list of auth instances to be used for this endpoint. Sync endpoints must use instances of dmr.security.SyncAuth. Async endpoints must use instances of dmr.security.AsyncAuth. When set it to None it means that auth is disabled for this endpoint.

Type:

list[SyncAuth | AsyncAuth] | None

throttling

Sequence of throttle instances to be used for this endpoint. Sync endpoints must use instances of dmr.throttling.SyncThrottle. Async endpoints must use instances of dmr.throttling.AsyncThrottle. Set it to None to disable throttling of this endpoint.

Type:

tuple[SyncThrottle | AsyncThrottle, …] | None

throttling_before_auth

Sequence of throttle instances to be used before auth checks.

Type:

tuple[SyncThrottle | AsyncThrottle, …] | None

throttling_after_auth

Sequence of throttle instances to be used after auth checks.

Type:

tuple[SyncThrottle | AsyncThrottle, …] | None

throttling_allow_unsafe_cache

Should this endpoint allow unsafe throttle Django cache backends?

Type:

bool | None

exclude_validate_responses

Set of status codes that we don’t validate, even when validate_responses is enabled.

Type:

frozenset[http.HTTPStatus]

no_validate_http_spec

Set of checks that user wants to disable for validation in this endpoint.

Type:

frozenset[HttpSpec]

allowed_http_methods

Set of extra HTTP methods that are allowed for this endpoint.

Type:

frozenset[str]

semantic_responses

Should semantic responses from different providers be collected?

Type:

bool

exclude_semantic_responses

Set of semantic responses that user wants to disable.

Type:

frozenset[http.HTTPStatus]

validate_events

Should this endpoint validate events? If not set, defaults to the validate_responses value. This value only matters if the response will be a streaming response that supports event validation.

Type:

bool

summary

A short summary of what the operation does.

Type:

_StrOrPromise | None

description

A verbose explanation of the operation behavior.

Type:

_StrOrPromise | None

tags

A list of tags for API documentation control. Used to group operations in OpenAPI documentation.

Type:

list[str] | None

operation_id

Unique string used to identify the operation.

Type:

str | None

deprecated

Declares this operation to be deprecated.

Type:

bool

security

A declaration of which security mechanisms can be used for this operation. List of security requirement objects.

external_docs

Additional external documentation for this operation.

Type:

ExternalDocumentation | None

callbacks

A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a Callback Object that describes a request that may be initiated by the API provider and the expected responses.

Type:

dict[str, Callback | Reference] | None

servers

An alternative servers array to service this operation. If a servers array is specified at the Path Item Object or OpenAPI Object level, it will be overridden by this value.

Type:

list[Server] | None

ignore_from_spec

If set to True, this endpoint would not be added to the final OpenAPI spec.

Type:

bool

method can be a custom name, not specified in http.HTTPMethod enum, when allowed_http_methods is used for endpoint definition. This might be useful for cases like when you need to define a method like query, which is not yet formally accepted. Or provide domain specific HTTP methods.

See also

https://www.ietf.org/archive/id/draft-ietf-httpbis-safe-method-w-body-05.html

__post_init__() → None

Set pre-computed fields.

collect_response_specs(controller_cls: type[Controller[BaseSerializer]], existing_responses: dict[HTTPStatus, ResponseSpec]) → list[ResponseSpec]

Collect unique responses for all possible response providers.

response_spec_providers() → list[ResponseSpecProvider]

Determine: from where we should collect response schemas.

Override this method in your own metadata classes if you want more or less response spec providers.

For example: you can add some custom field to Controller like checks=. And you can subclass EndpointMetadata to also contain checks field and override this method to also include response specs from this field.

Define semantic_responses to False on settings or controller level to disable semantic responses collection.

@dmr.endpoint.modify(*, error_handler: None = None, status_code: HTTPStatus | None = None, headers: Mapping[str, NewHeader | HeaderSpec] | None = None, cookies: Mapping[str, NewCookie | CookieSpec] | None = None, validate_responses: bool | None = None, exclude_validate_responses: Set[HTTPStatus] | None = frozenset(), semantic_responses: bool | None = None, exclude_semantic_responses: Set[HTTPStatus] | None = frozenset(), validate_events: bool | None = None, extra_responses: list[ResponseSpec] | None = None, no_validate_http_spec: Set[HttpSpec] | None = frozenset(), parsers: Sequence[Parser] | None = None, renderers: Sequence[Renderer] | None = None, validate_negotiation: bool | None = None, auth: Sequence[Never] | None = (), throttling: Sequence[Never] | None = (), throttling_allow_unsafe_cache: bool | sentinel | None = EMPTY, summary: _StrOrPromise | None = None, description: _StrOrPromise | None = None, tags: list[str] | None = None, operation_id: str | None = None, deprecated: bool = False, external_docs: ExternalDocumentation | None = None, callbacks: dict[str, Callback | Reference] | None = None, servers: list[Server] | None = None, links: dict[str, Link | Reference] | None = None, response_description: str | None = None, ignore_from_spec: bool | None = None) → ModifyAnyCallable

@dmr.endpoint.modify(*, error_handler: AsyncErrorHandler | None = None, status_code: HTTPStatus | None = None, headers: Mapping[str, NewHeader | HeaderSpec] | None = None, cookies: Mapping[str, NewCookie | CookieSpec] | None = None, validate_responses: bool | None = None, exclude_validate_responses: Set[HTTPStatus] | None = frozenset(), semantic_responses: bool | None = None, exclude_semantic_responses: Set[HTTPStatus] | None = frozenset(), validate_events: bool | None = None, extra_responses: list[ResponseSpec] | None = None, no_validate_http_spec: Set[HttpSpec] | None = frozenset(), parsers: Sequence[Parser] | None = None, renderers: Sequence[Renderer] | None = None, validate_negotiation: bool | None = None, auth: Sequence[AsyncAuth] | None = (), throttling: Sequence[AsyncThrottle] | None = (), throttling_allow_unsafe_cache: bool | sentinel | None = EMPTY, summary: _StrOrPromise | None = None, description: _StrOrPromise | None = None, tags: list[str] | None = None, operation_id: str | None = None, deprecated: bool = False, external_docs: ExternalDocumentation | None = None, callbacks: dict[str, Callback | Reference] | None = None, servers: list[Server] | None = None, links: dict[str, Link | Reference] | None = None, response_description: str | None = None, ignore_from_spec: bool | None = None) → ModifyAsyncCallable

@dmr.endpoint.modify(*, error_handler: SyncErrorHandler | None = None, status_code: HTTPStatus | None = None, headers: Mapping[str, NewHeader | HeaderSpec] | None = None, cookies: Mapping[str, NewCookie | CookieSpec] | None = None, validate_responses: bool | None = None, exclude_validate_responses: Set[HTTPStatus] | None = frozenset(), semantic_responses: bool | None = None, exclude_semantic_responses: Set[HTTPStatus] | None = frozenset(), validate_events: bool | None = None, extra_responses: list[ResponseSpec] | None = None, no_validate_http_spec: Set[HttpSpec] | None = frozenset(), parsers: Sequence[Parser] | None = None, renderers: Sequence[Renderer] | None = None, validate_negotiation: bool | None = None, auth: Sequence[SyncAuth] | None = (), throttling: Sequence[SyncThrottle] | None = (), throttling_allow_unsafe_cache: bool | sentinel | None = EMPTY, summary: _StrOrPromise | None = None, description: _StrOrPromise | None = None, tags: list[str] | None = None, operation_id: str | None = None, deprecated: bool = False, external_docs: ExternalDocumentation | None = None, callbacks: dict[str, Callback | Reference] | None = None, servers: list[Server] | None = None, links: dict[str, Link | Reference] | None = None, response_description: str | None = None, ignore_from_spec: bool | None = None) → ModifySyncCallable

Decorator to modify endpoints that return raw model data.

Apply it to change some API parts:

>>> from http import HTTPStatus
>>> from dmr import Controller, modify
>>> from dmr.plugins.pydantic import PydanticSerializer

>>> class TaskController(Controller[PydanticSerializer]):
...     @modify(status_code=HTTPStatus.ACCEPTED)
...     def post(self) -> list[int]:
...         return [1, 2]  # id of tasks you have started

Parameters:

• status_code – Shows status_code in the documentation. When status_code is passed, always use it by default. When not provided, we use smart inference based on the HTTP method name for default returned response.

• headers – Shows headers in the documentation. When headers are passed we will add them for the default response.

• cookies – Shows cookies in the documentation. When cookies are passed we will add them for the default response.

• validate_responses – Do we have to run runtime validation of responses for this endpoint? Customizable via global setting, per controller, and per endpoint. Here we only store the per endpoint information.

• exclude_validate_responses – Set of status codes that we don’t validate, even when validate_responses is enabled. Useful for errors like 500 that can be raised from anywhere and that you might not want to describe.

• semantic_responses – Should semantic responses be collected from different providers for this endpoint.

• exclude_semantic_responses – Set of semantic responses status codes that user wants to disable.

• validate_events – Should this endpoint validate events? If not set, defaults to the validate_responses value. This value only matters if the response will be a streaming response that supports event validation.

• extra_responses – List of extra responses that this endpoint can return.

• no_validate_http_spec – Set of http spec validation checks that we disable for this endpoint.

• error_handler – Callback function to be called when this endpoint faces an exception.

• parsers – Sequence of types to be used for this endpoint to parse incoming request’s body. All types must be subtypes of Parser.

• renderers – Sequence of types to be used for this endpoint to render response’s body. All types must be subtypes of Renderer.

• validate_negotiation – Should we validate that returned response’s Content-Type header matches the one that we inferred in the negotiation process?

• auth – Sequence of auth instances to be used for this endpoint. Sync endpoints must use instances of dmr.security.SyncAuth. Async endpoints must use instances of dmr.security.AsyncAuth. Set it to None to disable auth for this endpoint.

• throttling – Sequence of throttle instances to be used for this endpoint. Sync endpoints must use instances of dmr.throttling.SyncThrottle. Async endpoints must use instances of dmr.throttling.AsyncThrottle. Set it to None to disable throttling of this endpoint.

• throttling_allow_unsafe_cache – Should this endpoint allow unsafe throttle Django cache backends?

• summary – A short summary of what the operation does.

• description – A verbose explanation of the operation behavior.

• tags – A list of tags for API documentation control. Used to group operations in OpenAPI documentation.

• operation_id – Unique string used to identify the operation.

• deprecated – Declares this operation to be deprecated.

• external_docs – Additional external documentation for this operation.

• callbacks – A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a Callback Object that describes a request that may be initiated by the API provider and the expected responses.

• servers – An alternative servers array to service this operation.

• links – Possible links to other OpenAPI operations.

• response_description – Description for the generated response object.

• ignore_from_spec – If set to True, this endpoint would not be added to the final OpenAPI spec.

Returns:

The same function with __dmr_payload__ payload instance.

Warning

Do not disable validate_responses unless this is performance critical for you!

@dmr.endpoint.validate(response: ResponseSpec, /, *responses: ResponseSpec, error_handler: None = None, validate_responses: bool | None = None, exclude_validate_responses: Set[HTTPStatus] | None = frozenset(), semantic_responses: bool | None = None, exclude_semantic_responses: Set[HTTPStatus] | None = frozenset(), validate_events: bool | None = None, no_validate_http_spec: Set[HttpSpec] | None = frozenset(), parsers: Sequence[Parser] | None = None, renderers: Sequence[Renderer] | None = None, validate_negotiation: bool | None = None, auth: Sequence[Never] | None = (), throttling: Sequence[Never] | None = (), throttling_allow_unsafe_cache: bool | sentinel | None = EMPTY, summary: _StrOrPromise | None = None, description: _StrOrPromise | None = None, tags: list[str] | None = None, operation_id: str | None = None, deprecated: bool = False, external_docs: ExternalDocumentation | None = None, callbacks: dict[str, Callback | Reference] | None = None, servers: list[Server] | None = None, ignore_from_spec: bool | None = None) → Callable[[Callable[[_ParamT], _ResponseT]], Callable[[_ParamT], _ResponseT]]

@dmr.endpoint.validate(response: ResponseSpec, /, *responses: ResponseSpec, error_handler: AsyncErrorHandler | None = None, validate_responses: bool | None = None, exclude_validate_responses: Set[HTTPStatus] | None = frozenset(), semantic_responses: bool | None = None, exclude_semantic_responses: Set[HTTPStatus] | None = frozenset(), validate_events: bool | None = None, no_validate_http_spec: Set[HttpSpec] | None = frozenset(), parsers: Sequence[Parser] | None = None, renderers: Sequence[Renderer] | None = None, validate_negotiation: bool | None = None, auth: Sequence[AsyncAuth] | None = (), throttling: Sequence[AsyncThrottle] | None = (), throttling_allow_unsafe_cache: bool | sentinel | None = EMPTY, summary: _StrOrPromise | None = None, description: _StrOrPromise | None = None, tags: list[str] | None = None, operation_id: str | None = None, deprecated: bool = False, external_docs: ExternalDocumentation | None = None, callbacks: dict[str, Callback | Reference] | None = None, servers: list[Server] | None = None, ignore_from_spec: bool | None = None) → Callable[[Callable[[_ParamT], Awaitable[HttpResponseBase]]], Callable[[_ParamT], Awaitable[HttpResponseBase]]]

@dmr.endpoint.validate(response: ResponseSpec, /, *responses: ResponseSpec, error_handler: SyncErrorHandler | None = None, validate_responses: bool | None = None, exclude_validate_responses: Set[HTTPStatus] | None = frozenset(), semantic_responses: bool | None = None, exclude_semantic_responses: Set[HTTPStatus] | None = frozenset(), validate_events: bool | None = None, no_validate_http_spec: Set[HttpSpec] | None = frozenset(), parsers: Sequence[Parser] | None = None, renderers: Sequence[Renderer] | None = None, validate_negotiation: bool | None = None, auth: Sequence[SyncAuth] | None = (), throttling: Sequence[SyncThrottle] | None = (), throttling_allow_unsafe_cache: bool | sentinel | None = EMPTY, summary: _StrOrPromise | None = None, description: _StrOrPromise | None = None, tags: list[str] | None = None, operation_id: str | None = None, deprecated: bool = False, external_docs: ExternalDocumentation | None = None, callbacks: dict[str, Callback | Reference] | None = None, servers: list[Server] | None = None, ignore_from_spec: bool | None = None) → Callable[[Callable[[_ParamT], HttpResponseBase]], Callable[[_ParamT], HttpResponseBase]]

Decorator to validate responses from endpoints that return HttpResponse.

Apply it to validate important API parts:

>>> from http import HTTPStatus
>>> from django.http import HttpResponse
>>> from dmr import Controller, validate, ResponseSpec
>>> from dmr.plugins.pydantic import PydanticSerializer

>>> class TaskController(Controller[PydanticSerializer]):
...     @validate(
...         ResponseSpec(
...             return_type=list[int],
...             status_code=HTTPStatus.OK,
...         ),
...     )
...     def post(self) -> HttpResponse:
...         return HttpResponse(b'[1, 2]', status=HTTPStatus.OK)

Response validation can be disabled for extra speed by sending validate_responses falsy parameter or by setting this configuration in your settings.py file:

settings.py

>>> DMR_SETTINGS = {'validate_responses': False}

Parameters:

• response – The main response that this endpoint is allowed to return.

• responses – A collection of other responses that are allowed to be returned from this endpoint.

• validate_responses – Do we have to run runtime validation of responses for this endpoint? Customizable via global setting, per controller, and per endpoint. Here we only store the per endpoint information.

• exclude_validate_responses – Set of status codes that we don’t validate, even when validate_responses is enabled. Useful for errors like 500 that can be raised from anywhere and that you might not want to describe.

• semantic_responses – Should semantic responses be collected from different providers for this endpoint.

• exclude_semantic_responses – Set of semantic responses status codes that user wants to disable.

• validate_events – Should this endpoint validate events? If not set, defaults to the validate_responses value. This value only matters if the response will be a streaming response that supports event validation.

• no_validate_http_spec – Set of http spec validation checks that we disable for this endpoint.

• error_handler – Callback function to be called when this endpoint faces an exception.

• parsers – Sequence of types to be used for this endpoint to parse incoming request’s body. All types must be subtypes of Parser.

• renderers – Sequence of types to be used for this endpoint to render response’s body. All types must be subtypes of Renderer.

• validate_negotiation – Should we validate that returned response’s Content-Type header matches the one that we inferred in the negotiation process?

• auth – Sequence of auth instances to be used for this endpoint. Sync endpoints must use instances of dmr.security.SyncAuth. Async endpoints must use instances of dmr.security.AsyncAuth. Set it to None to disable auth for this endpoint.

• throttling – Sequence of throttle instances to be used for this endpoint. Sync endpoints must use instances of dmr.throttling.SyncThrottle. Async endpoints must use instances of dmr.throttling.AsyncThrottle. Set it to None to disable throttling of this endpoint.

• throttling_allow_unsafe_cache – Should this controller allow unsafe throttle Django cache backends?

• summary – A short summary of what the operation does.

• description – A verbose explanation of the operation behavior.

• tags – A list of tags for API documentation control. Used to group operations in OpenAPI documentation.

• operation_id – Unique string used to identify the operation.

• deprecated – Declares this operation to be deprecated.

• external_docs – Additional external documentation for this operation.

• callbacks – A map of possible out-of band callbacks related to the parent operation. The key is a unique identifier for the Callback Object. Each value in the map is a Callback Object that describes a request that may be initiated by the API provider and the expected responses.

• servers – An alternative servers array to service this operation.

• ignore_from_spec – If set to True, this endpoint would not be added to the final OpenAPI spec.

Returns:

The same function with __dmr_payload__ payload instance.

Warning

Do not disable validate_responses unless this is performance critical for you!

@dmr.endpoint.request_endpoint(request: HttpRequest, *, strict: Literal[True]) → Endpoint

@dmr.endpoint.request_endpoint(request: HttpRequest, *, strict: bool = False) → Endpoint | None

Return an instance of the Endpoint that was used for this request.

When strict is passed and request has no endpoint, we raise AttributeError. This can happen for 405 responses, for example. They don’t have endpoints. All others do.

Added in version 0.7.0.

Response, headers and cookies

class dmr.metadata.ResponseSpecProvider

Base abstract class to provide extra response schemas.

abstractmethod provide_response_specs(metadata: EndpointMetadata, controller_cls: type[Controller[BaseSerializer]], existing_responses: Mapping[HTTPStatus, ResponseSpec]) → list[ResponseSpec]

Provide custom response specs.

Will be called to inject response specs from different components into the resulting endpoint metadata.

class dmr.metadata.ResponseSpec(return_type: Any, *, status_code: HTTPStatus, headers: Mapping[str, HeaderSpec] | None = None, cookies: Mapping[str, CookieSpec] | None = None, limit_to_content_types: Set[str] | None = None, streaming: bool = False, description: _StrOrPromise | None = None, links: dict[str, Link | Reference] | None = None)

Represents a single API response specification.

return_type

Shows return_type in the documentation as returned model schema. We validate return_type to match the returned response content by default, but it can be turned off.

Type:

Any

status_code

Shows status_code in the documentation. We validate status_code to match the specified one when HttpResponse is returned.

Type:

http.HTTPStatus

headers

Shows headers in the documentation. When passed, we validate that all given required headers are present in the final response.

Type:

collections.abc.Mapping[str, HeaderSpec] | None

cookies

Shows cookies in the documentation. When passed, we validate that all given required cookies are present in the final response.

Type:

collections.abc.Mapping[str, CookieSpec] | None

streaming

Are we working with the stream response?

Type:

bool

limit_to_content_types

This response can only happen only for given content types. By default, when equals to None, all responses can happen for all content types.

Type:

collections.abc.Set[str] | None

description

Text comment about what this response represents.

Type:

_StrOrPromise | None

links

Possible links to other OpenAPI operations.

Type:

dict[str, Link | Reference] | None

We use this structure to validate responses and render them in OpenAPI.

__post_init__() → None

If headers and cookies are not set, look for metadata and use it.

get_schema(metadata: EndpointMetadata, serializer: type[BaseSerializer], context: OpenAPIContext) → Response

Returns the OpenAPI schema for the response.

Can be customized in subclasses. Be careful when overriding the schema generation. We don’t provide any validations for the returned schema. Ensure that it is in sync with the actual response.

class dmr.metadata.ResponseSpecMetadata(*, headers: Mapping[str, HeaderSpec] | None = None, cookies: Mapping[str, CookieSpec] | None = None)

Special type to be used in Annotate to provide header and cookie specs.

headers

Shows headers in the documentation. When passed, we validate that all given required headers are present in the final response.

Type:

collections.abc.Mapping[str, HeaderSpec] | None

cookies

Shows cookies in the documentation. When passed, we validate that all given required cookies are present in the final response.

Type:

collections.abc.Mapping[str, CookieSpec] | None

Added in version 0.7.0.

class dmr.metadata.ResponseModification(*, return_type: Any, status_code: HTTPStatus, headers: Mapping[str, NewHeader | HeaderSpec] | None, cookies: Mapping[str, NewCookie | CookieSpec] | None, streaming: bool, description: _StrOrPromise | None, links: dict[str, Link | Reference] | None)

Represents a single API modification.

Parameters:

• return_type – Shows return_type in the documentation as returned model schema. We validate return_type to match the returned response content by default, but it can be turned off.

• status_code – Shows status_code in the documentation. We validate status_code to match the specified one when HttpResponse is returned.

• headers – Shows headers in the documentation. Headers passed here will be added to the final response.

• cookies – Shows cookies in the documentation. New cookies passed here will be added to the final response.

• streaming – Are we working with the stream response?

• description – Text comment about what this response represents.

• links – Possible links to other OpenAPI operations.

We use this structure to modify the default response.

actionable_cookies() → Mapping[str, NewCookie] | None

Returns an optional mapping of cookies that should be added.

actionable_headers() → Mapping[str, NewHeader] | None

Returns an optional mapping of headers that should be added.

build_headers(renderer: Renderer) → dict[str, str]

Returns headers with values for raw data endpoints.

infer_return_type() → Any

Infers return type if it needs some extra love.

response_spec_cls

alias of ResponseSpec

to_spec() → ResponseSpec

Convert response modification to response description.

exception dmr.response.APIError(raw_data: _ItemT, *, status_code: HTTPStatus, headers: Mapping[str, str] | None = None, cookies: Mapping[str, NewCookie] | None = None)

Special class to fast return errors from API.

Does perform the regular response validation.

You can use APIError everywhere: - In endpoints - In components when parsing something - In auth if you want to change the response code

Usage:

>>> from http import HTTPStatus
>>> from dmr import (
...     APIError,
...     Controller,
...     ResponseSpec,
...     modify,
... )
>>> from dmr.errors import ErrorType
>>> from dmr.plugins.pydantic import PydanticSerializer

>>> class UserController(Controller[PydanticSerializer]):
...     @modify(
...         extra_responses=[
...             ResponseSpec(
...                 str,
...                 status_code=HTTPStatus.NOT_FOUND,
...             ),
...         ],
...     )
...     def get(self) -> str:
...         raise APIError(
...             self.format_error(
...                 'This API endpoint is not implemented yet',
...                 error_type=ErrorType.user_msg,
...             ),
...             status_code=HTTPStatus.NOT_FOUND,
...         )

dmr.response.build_response(serializer: type['BaseSerializer'], *, raw_data: Any, method: HTTPMethod | str, headers: Mapping[str, str] | None = None, cookies: Mapping[str, NewCookie] | None = None, status_code: HTTPStatus | None = None, renderer: Renderer | None = None) → HttpResponse

dmr.response.build_response(serializer: type['BaseSerializer'], *, raw_data: Any, status_code: HTTPStatus, method: None = None, headers: Mapping[str, str] | None = None, cookies: Mapping[str, NewCookie] | None = None, renderer: Renderer | None = None) → HttpResponse

Utility that returns the actual HttpResponse object from its parts.

Does not perform extra validation, only regular response validation. We need this as a function, so it can be called when no endpoints exist.

Do not use directly, prefer using to_response() method. Unless you are using a lower-level API. Like in middlewares, for example.

You have to provide either method or status_code.

final class dmr.headers.HeaderSpec(*, description: _StrOrPromise | None = None, deprecated: bool = False, example: str | None = None, required: bool = True, skip_validation: bool = False)

Existing header that django.http.HttpResponse already has.

This class is used to describe the existing reality. Used for validation that all required headers are present.

description

Documentation, why this header is needed and what it does.

deprecated

Whether this header is deprecated.

example

Documentation, what can be given as values in this header.

required

Whether or not this header can be missing.

Type:

bool

skip_validation

Is true, when header is only used for schema purposes, without any runtime validation. This might be useful, when this header will be set after our framework’s validation. For example, by django.contrib.sessions.middleware.SessionMiddleware or by HTTP proxy. This header might be present in runtime or might be missing.

Type:

bool

to_spec() → HeaderSpec

Needed for API compat with NewHeader.

final class dmr.headers.NewHeader(*, description: _StrOrPromise | None = None, deprecated: bool = False, example: str | None = None, value: str)

New header that will be added to django.http.HttpResponse by us.

This class is used to add new entries to response’s headers. Is not used for validation.

description

Documentation, why this header is needed and what it does.

deprecated

Whether this header is deprecated.

example

Documentation, what can be given as values in this header.

value

value to be set in this new header.

Type:

str

to_spec() → HeaderSpec

Convert header type.

final class dmr.cookies.CookieSpec(*, path: str = '/', max_age: int | None = None, expires: int | None = None, domain: str | None = None, secure: bool | None = None, httponly: bool | None = None, samesite: Literal['lax', 'strict', 'none'] = 'lax', description: _StrOrPromise | None = None, required: bool = True, skip_validation: bool = False)

Description of a single cookie in Set-Cookie header.

path

Path fragment that must exist in the request url for the cookie to be valid. Defaults to /.

max_age

Maximal age of the cookie before its invalidated.

expires

Seconds from now until the cookie expires.

domain

Domain for which the cookie is valid.

secure

Https is required for the cookie.

httponly

Forbids javascript to access the cookie via document.cookie.

samesite

Controls whether or not a cookie is sent with cross-site requests. Defaults to 'lax'.

description

Description of the response cookie header for OpenAPI documentation.

Type:

_StrOrPromise | None

required

Defines that this cookie can be missing in some cases.

Type:

bool

skip_validation

Is true, when cookie is only used for schema purposes, without any runtime validation. This might be useful, when this cookie will be set after our framework’s validation. For example, by django.contrib.sessions.middleware.SessionMiddleware or by HTTP proxy. This cookie might be present in runtime or might be missing.

Type:

bool

See also

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie

is_equal(other: Morsel[str]) → bool

Compare this object with SimpleCookie like object.

to_spec() → CookieSpec

API for compatibility with NewCookie.

final class dmr.cookies.NewCookie(*, path: str = '/', max_age: int | None = None, expires: int | None = None, domain: str | None = None, secure: bool | None = None, httponly: bool | None = None, samesite: Literal['lax', 'strict', 'none'] = 'lax', value: str)

New cookie to be set for the response.

value

Value for the cookie.

Type:

str

path

Path fragment that must exist in the request url for the cookie to be valid. Defaults to /.

Type:

str

max_age

Maximal age of the cookie before its invalidated.

Type:

int | None

expires

Seconds from now until the cookie expires.

Type:

int | None

domain

Domain for which the cookie is valid.

Type:

str | None

secure

Https is required for the cookie.

Type:

bool | None

httponly

Forbids javascript to access the cookie via document.cookie.

Type:

bool | None

samesite

Controls whether or not a cookie is sent with cross-site requests. Defaults to 'lax'.

Type:

Literal[‘lax’, ‘strict’, ‘none’]

See also

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie

as_dict() → dict[str, Any]

Converts to a dictionary .

to_spec() → CookieSpec

Converts the modification to spec.

dmr.cookies.set_cookies(response: HttpResponseBase, cookies: Mapping[str, NewCookie] | None) → None

Set cookies for the HTTP response.

Validation

class dmr.validation.ModifyEndpointPayload(*, summary: _StrOrPromise | None = None, description: _StrOrPromise | None = None, tags: list[str] | None = None, operation_id: str | None = None, deprecated: bool = False, security: list[SecurityRequirement] | None = None, external_docs: ExternalDocumentation | None = None, callbacks: dict[str, Callback | Reference] | None = None, servers: list[Server] | None = None, ignore_from_spec: bool | None = None, validate_responses: bool | None = None, exclude_validate_responses: Set[HTTPStatus] | None = None, semantic_responses: bool | None = None, exclude_semantic_responses: Set[HTTPStatus] | None = None, validate_events: bool | None = None, error_handler: Callable[[Endpoint, Controller[BaseSerializer], Exception], HttpResponse] | Callable[[Endpoint, Controller[BaseSerializer], Exception], Awaitable[HttpResponse]] | None = None, no_validate_http_spec: Set[HttpSpec] | None = None, parsers: Sequence[Parser] | None = None, renderers: Sequence[Renderer] | None = None, validate_negotiation: bool | None = None, auth: Sequence[SyncAuth] | Sequence[AsyncAuth] | None = (), throttling: Sequence[SyncThrottle] | Sequence[AsyncThrottle] | None = (), throttling_allow_unsafe_cache: bool | sentinel | None = EMPTY, responses: list[ResponseSpec] | None, status_code: HTTPStatus | None, headers: Mapping[str, NewHeader | HeaderSpec] | None, cookies: Mapping[str, NewCookie | CookieSpec] | None, response_description: str | None, links: dict[str, Link | Reference] | None)

Payload created by @modify.

class dmr.validation.ValidateEndpointPayload(*, summary: _StrOrPromise | None = None, description: _StrOrPromise | None = None, tags: list[str] | None = None, operation_id: str | None = None, deprecated: bool = False, security: list[SecurityRequirement] | None = None, external_docs: ExternalDocumentation | None = None, callbacks: dict[str, Callback | Reference] | None = None, servers: list[Server] | None = None, ignore_from_spec: bool | None = None, validate_responses: bool | None = None, exclude_validate_responses: Set[HTTPStatus] | None = None, semantic_responses: bool | None = None, exclude_semantic_responses: Set[HTTPStatus] | None = None, validate_events: bool | None = None, error_handler: Callable[[Endpoint, Controller[BaseSerializer], Exception], HttpResponse] | Callable[[Endpoint, Controller[BaseSerializer], Exception], Awaitable[HttpResponse]] | None = None, no_validate_http_spec: Set[HttpSpec] | None = None, parsers: Sequence[Parser] | None = None, renderers: Sequence[Renderer] | None = None, validate_negotiation: bool | None = None, auth: Sequence[SyncAuth] | Sequence[AsyncAuth] | None = (), throttling: Sequence[SyncThrottle] | Sequence[AsyncThrottle] | None = (), throttling_allow_unsafe_cache: bool | sentinel | None = EMPTY, responses: list[ResponseSpec])

Payload created by @validate.

Serialization

class dmr.serializer.BaseSerializer

Abstract base class for data serialization.

What serializer does?

1. It provides serialization and deserialization hooks for parser and renderer. So different parsers and renderers will work similarly. This way you can modify all the serialization logic in one place and not adjust all possible parsers or renderers

2. It provides validation for raw python data, see dmr.serializer.BaseSerializer.from_python() method

3. It provides serialization for related complex utility objects like validation errors and responses that don’t have .content attribute. For example: file and sse responses

validation_error

Exception type that is used for validation errors. Required to be set in subclasses.

Type:

ClassVar[type[Exception]]

optimizer

Endpoint optimizer. Type that pre-compiles / creates / caches models in import time. Required to be set in subclasses.

Type:

ClassVar[type[dmr.serializer.BaseEndpointOptimizer]]

schema_generator

Generates schema and schema names for the OpenAPI.

Type:

ClassVar[type[dmr.serializer.BaseSchemaGenerator]]

abstractmethod classmethod deserialize(buffer: bytes | bytearray, *, parser: Parser, request: HttpRequest, model: Any) → Any

Convert json bytestring to structured data.

classmethod deserialize_hook(target_type: type[Any], to_deserialize: Any) → Any

Customize how some objects are deserialized from json.

Only add types that are common for all potential plugins here. Should be called inside deserialize().

abstractmethod classmethod from_python(unstructured: Any, model: Any, *, strict: bool | None, extra_namespace: Mapping[str, Any] | None = None) → Any

Parse unstructured data from python primitives into model.

Raises cls.validation_error when something cannot be parsed.

Parameters:

• unstructured – Python objects to be parsed / validated.

• model – Python type to serve as a model. Can be any type hints that user can theoretically supply. Depends on the serialization plugin.

• strict – Whether we use more strict validation rules. For example, it is fine for a request validation to be less strict in some cases and allow type coercition. But, response types need to be strongly validated.

• extra_namespace – Optional namespace to load type annotations from. It is useful, when using stringified or lazy type annotations.

Returns:

Structured and validated data.

Changed in version 0.13.0: Added extra_namespace parameter.

classmethod is_supported(pluggable: Parser | Renderer) → bool

Is this parser or renderer supported?

When defining custom serializers you can specify what kind of parser and renders you support. Adding a combination of unsupported serializer and parser / render will raise an import-time validation error.

abstractmethod classmethod serialize(structure: Any, *, renderer: Renderer) → bytes

Convert structured data to json bytestring.

classmethod serialize_hook(to_serialize: Any) → Any

Customize how some objects are serialized into json.

Only add types that are common for all potential plugins here. Should be called inside serialize().

abstractmethod classmethod serialize_validation_error(exc: Exception) → list[ErrorDetail]

Convert specific serializer’s validation errors into simple python data.

Parameters:

exc – A serialization exception to be serialized into simpler type. For example, pydantic has a complex pydantic_core.ValidationError type. That can’t be converted to a simpler error message easily.

Returns:

Simple python object - exception converted to json.

abstractmethod classmethod to_python(structured: Any) → Any

Unstructure structured data from a model into Python primitives.

Parameters:

structured – Model instance.

Returns:

Unstructured data.

class dmr.serializer.BaseEndpointOptimizer

Plugins might often need to run some specific preparations for endpoints.

To achieve that we provide an explicit API for that.

abstractmethod classmethod optimize_endpoint(metadata: EndpointMetadata) → None

Optimize the endpoint.

Parameters:

metadata – Endpoint metadata to optimize.

class dmr.endpoint.SerializerContext(func: Callable[[...], Any], controller_cls: type[Controller[BaseSerializer]], type_annotations: dict[str, Any])

Parse and bind request components for a controller.

This context collects raw data for all registered components, validates the combined payload in a single call using a cached TypedDict model, and then binds the parsed values back to the controller.

strict_validation

Whether or not to validate payloads in strict mode. Strict mode in some serializers does not allow implicit type conversions. Defaults to None, which means that we decide on a per-field basis if it is set, if not then on a per-model basis.

Type:

ClassVar[bool | None]

__call__(endpoint: Endpoint, controller: Controller[BaseSerializer]) → dict[str, Any]

Collect, validate, and bind component data to the controller.

Raises serializer.validation_error when provided data does not match the expected model.

component_builder_cls

alias of ComponentParserBuilder

class dmr.serializer.BaseSchemaGenerator

Generates JSON schema by the native serializer API.

abstractmethod classmethod get_schema(model: Any, ref_template: str, *, used_for_response: bool = False) → tuple[dict[str, Any], dict[str, Any]]

Provide JSON schema / OpenAPI spec for the given model.

Parameters:

• model – Model to generate JSON schema for.

• ref_template – Reference template to use for the references.

• used_for_response – Is this schema used for the response or request.

Raises:

Exception – when schema cannot be built. Can be any Exception subclass instance.

abstractmethod classmethod schema_name(model: Any) → str | None

Return a schema name for a model, if it exists.

It is done directly by the serializer, we don’t store any specific logic for it.

class dmr.components.ComponentParserBuilder(func: Callable[[...], Any], controller_cls: type[Controller[BaseSerializer]])

Find the component parser types in the MRO and find model types for them.

Validates that component parsers can’t have type vars as models at this point.

__call__(type_annotations: dict[str, Any]) → list[tuple[ComponentParser, Any, tuple[Any, ...]]]

Run the building process, infer type vars if needed.

type_var_inference_cls

alias of TypeVarInference

Routing

class dmr.routing.Router(prefix: str = '', urls: Iterable[URLPattern | URLResolver | URLExternal] = (), *, tags: Sequence[str] | None = None, deprecated: bool = False, ignore_from_spec: bool = False)

Collection of HTTP routes for REST framework.

prefix

URL prefix for all routes (e.g., ‘api/v1/’). Defaults to empty string ''.

urls

Sequence of URL patterns and resolvers.

tags

Optional sequence of tags to group operations in OpenAPI. These are merged with endpoint-level tags.

deprecated

Optional flag to mark all operations as deprecated. Combines with endpoint-level deprecated flag using OR logic.

ignore_from_spec

If set to True, all routes from this router are excluded from the generated OpenAPI specification. Runtime URL routing is not affected.

Note

tags and deprecated is not applied to external urls’ metadata. It is always included as-is.

Changed in version 0.7.0: Added tags and deprecated parameters.

Changed in version 0.13.0: Now you can pass external_path() objects in urls. Also accept any collections.abc.Sequence as tags. urls parameter is now optional.

Changed in version 0.15.0: Added ignore_from_spec parameter.

get_schema(context: OpenAPIContext) → OpenAPI

Builds OpenAPI specification.

This class orchestrates the process of generating a complete OpenAPI specification by collecting controllers from the router, generating path items for each controller, extracting shared components, and merging everything together with the configuration.

include(router: Router, *, namespace: str | None = None, app_name: str | None = None) → None

Include a router’s URLs under a given app name and namespace.

Added in version 0.13.0.

metadata_for(pattern: str) → RouterMetadata

Returns applied nested metadata from all router layers.

Raises:

KeyError – if pattern is not found.

Added in version 0.15.0.

to_urlpatterns(*, namespace: str | None = None, app_name: str | None = None) → URLResolver

Convert router instance into urlpatterns include API.

Can be used to include one router into another. Or to include a router into the final urlpatterns list.

Automatically uses our own faster path() function.

Added in version 0.14.0.

dmr.routing.build_404_handler(prefix: str, /, *prefixes: str, serializer: type[BaseSerializer], format_error: FormatError = <function format_error>, renderers: ~collections.abc.Sequence[Renderer] | None = None) → Callable[[HttpRequest, Exception], HttpResponse]

Create a 404 handler that returns a response with content negotiation.

All prefixes are normalized to start with a leading slash. If the request path matches any of them, a 404 response is returned using the same serializer and renderers as your API. If the client’s Accept does not match any renderer, the first configured renderer is used. For non-matching paths, Django’s default page_not_found handler is used.

Parameters:

• prefix – Path prefix (e.g. 'api/') for which to return API 404.

• *prefixes – Additional path prefixes.

• format_error – Callable used to build the error body for the response.

• serializer – Serializer class used to serialize the error body.

• renderers – Optional sequence of renderers. If omitted, uses renderers from settings.

See also

https://docs.djangoproject.com/en/stable/ref/views/#the-404-page-not-found-view

dmr.routing.build_500_handler(prefix: str, /, *prefixes: str, serializer: type[BaseSerializer], format_error: FormatError = <function format_error>, renderers: ~collections.abc.Sequence[Renderer] | None = None) → Callable[[HttpRequest], HttpResponse]

Create a 500 handler that returns a response with content negotiation.

All prefixes are normalized to start with a leading slash. If the request path matches any of them, a 500 response is returned using the same serializer and renderers as your API. If the client’s Accept does not match any renderer, the first configured renderer is used. For non-matching paths, Django’s default server_error handler is used.

Parameters:

• prefix – Path prefix (e.g. 'api/') for which to return API 500.

• *prefixes – Additional path prefixes.

• format_error – Callable used to build the error body for the response.

• serializer – Serializer class used to serialize the error body.

• renderers – Optional sequence of renderers. If omitted, uses renderers from settings.

See also

https://docs.djangoproject.com/en/stable/ref/views/#the-500-server-error-view

dmr.routing.path(route: _StrOrPromise, view: Callable[[...], HttpResponseBase | Coroutine[Any, Any, HttpResponseBase]], kwargs: dict[str, Any] | None = None, name: str | None = None) → URLPattern

dmr.routing.path(route: _StrOrPromise, view: tuple[Sequence[URLPattern | URLResolver], str | None, str | None], kwargs: dict[str, Any] | None = None, name: str | None = None) → URLResolver

dmr.routing.path(route: _StrOrPromise, view: Sequence[URLResolver | str], kwargs: dict[str, Any] | None = None, name: str | None = None) → URLResolver

Creates URL pattern using prefix-based matching for faster routing.

dmr.routing.external_path(route: _StrOrPromise, view: Callable[[...], HttpResponseBase | Coroutine[Any, Any, HttpResponseBase]], *, openapi: PathItem | None, kwargs: dict[str, Any] | None = None, name: str | None = None) → _URLExternal

Add an external path onto the DMR routing system.

Automatically uses our own faster path() function.

Parameters:

• route – String route for the view.

• view – Function or class view, supports both sync and async callables.

• openapi – OpenAPI metadata to show in the spec. Or None to hide this endpoint.

• kwargs – Init kwargs for the view.

• name – Name to resolve this URL.

Important

This function only works when including a URL into our own Router objects, not into the Django own urlpatterns.

Django check urls.E004 covers this statically.

See External views for more info.

Added in version 0.13.0.

Meta mixins

class dmr.options_mixins.MetaMixin

Mixin 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 dmr.controller.Controller type:

>>> from dmr import Controller
>>> from dmr.options_mixins import MetaMixin
>>> from dmr.plugins.pydantic import PydanticSerializer

>>> class SupportsOptionsHttpMethod(
...     MetaMixin,
...     Controller[PydanticSerializer],
... ): ...

meta() → HttpResponse

Default sync implementation for OPTIONS http method.

class dmr.options_mixins.AsyncMetaMixin

Mixin 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 dmr.controller.Controller type:

>>> from dmr import Controller
>>> from dmr.options_mixins import AsyncMetaMixin
>>> from dmr.plugins.pydantic import PydanticSerializer

>>> class SupportsOptionsHttpMethod(
...     AsyncMetaMixin,
...     Controller[PydanticSerializer],
... ): ...

async meta() → HttpResponse

Default async implementation for OPTIONS http method.

Exceptions

final exception dmr.exceptions.UnsolvableAnnotationsError

Bases: Exception

Raised when we can’t solve function’s annotations using get_type_hints.

Only raised when there are no other options.

final exception dmr.exceptions.EndpointMetadataError

Bases: Exception

Raised when user didn’t specify some required endpoint metadata.

final exception dmr.exceptions.DataParsingError

Bases: Exception

Raised when input data cannot be parsed.

final exception dmr.exceptions.RequestSerializationError

Bases: Exception

Raised when we fail to parse some request part.

final exception dmr.exceptions.ResponseSchemaError

Bases: Exception

Raised when we fail to validate some response part.

Can only happen when response validation is enabled. Does not show up in the response schema if validation is disabled.

final exception dmr.exceptions.ValidationError(payload: list[ErrorDetail], *, status_code: HTTPStatus = HTTPStatus.UNPROCESSABLE_ENTITY)

Bases: Exception

Raised when we cannot properly validate request or response models.

It should be only raised when serializer raise its internal validation error.

It is an universal way of handling validation errors from different serializers.

final exception dmr.exceptions.NotAcceptableError

Bases: Exception

Raised when client provides wrong Accept header.

final exception dmr.exceptions.NotAuthenticatedError(msg: str | Promise | None = None, *, headers: dict[str, str] | None = None)

Bases: Exception

Raised when we fail to authenticate a user.

final exception dmr.exceptions.InternalServerError

Bases: Exception

Indicates that something is broken on our side.

If settings.DEBUG is enabled, we share the details: what has happened. If it is disabled, we just show a generic message.

final exception dmr.exceptions.TooManyRequestsError(msg: str | Promise | None = None, *, headers: dict[str, str] | None = None)

Bases: Exception

Raised when user fails the throttling check.

Utilities

dmr.types.Json: TypeAlias = typing.Any

Recursive type alias for JSON data.

What is JSON? Integers, floats, booleans, strings, list of them and dicts of them, which keys are always strings.

In runtime it is always typing.Any because of the parsing complexity, while in type checking it correctly defined.

We don’t recommend using it for anything serious, it is better to define real models instead.

dmr.types.EMPTY: Final = EMPTY

Default singleton for empty values.

class dmr.types.AnnotationsContext(*, globalns: dict[str, Any] | None = None, localns: Mapping[str, Any] | None = None, include_extras: bool = True, format: Format | None = None)

Annotation evaluation context.

Use this type to change how controllers resolve type hints of their endpoints.

For example, one can change this function to use inspect.get_annotations() function. Or to have some pre-defined global names.

__call__(endpoint_func: Callable[[...], Any]) → dict[str, Any]

Get the annotations.

Parameters:

endpoint_func – function with return type annotation.

Returns:

Function’s parsed and solved return type.

Raises:

UnsolvableAnnotationsError – when annotation can’t be solved or when the annotation does not exist.

class dmr.types.TypeVarInference(to_infer: TypeVar, context: type[Any])

Inferences type variables to the applied real type values.

__call__() → dict[TypeVar, Any]

Run the inference.

Returns:

Mapping of type vars to its inferenced values. It can still be a type variable, if no real values are provided.

dmr.types.safe_typevar(typevar_name: str, *, stacklevel: int = 1, globalns: dict[str, Any] | None = None) → Any

Typing utility to allow passing typing.TypeVar safely.

By default mypy and other type-checkers would raise a typing error on a code like this:

>>> from typing import TypeVar
>>> from http import HTTPStatus
>>> from dmr import validate, ResponseSpec

>>> _ModelT = TypeVar('_ModelT')

>>> validate(
...     ResponseSpec(
...         # In traditional Python typing spec, it is not allowed
...         # to use type var in this context:
...         _ModelT,  # type: ignore[misc]
...         status_code=HTTPStatus.OK,
...     ),
... )
<function ...>

But, this function can help with this problem with no type errors:

>>> validate(
...     ResponseSpec(
...         safe_typevar('_ModelT'),
...         status_code=HTTPStatus.OK,
...     ),
... )
<function ...>

Parameters:

• typevar_name – TypeVar name to find in the globals.

• stacklevel – Levels of function frames to get globals from.

• globalns – Explicit globals namespace. Has a higher priority than stacklevel.

Raises:

KeyError – If typevar_name is not found in globalns.

Added in version 0.14.0.

Decorators

dmr.decorators.dispatch_decorator(func: Callable[[...], Any]) → Callable[[_TypeT], _TypeT]

Special helper to decorate class-based view’s dispatch method.

Use it directly on controllers, like so:

>>> from dmr import Controller
>>> from dmr.decorators import dispatch_decorator
>>> from dmr.plugins.pydantic import PydanticSerializer
>>> from django.contrib.auth.decorators import login_required

>>> @dispatch_decorator(login_required())
... class MyController(Controller[PydanticSerializer]):
...     def get(self) -> str:
...         return 'Logged in!'

In this example we would require all calls to all methods of MyController to require an existing authentication.

It also works for things like: - django.contrib.auth.decorators.login_not_required() - django.contrib.auth.decorators.user_passes_test() - django.contrib.auth.decorators.permission_required() - and any other default or custom django decorator

Danger

This will return non-json responses, without respecting your spec! Use with caution!

If you want full spec support, use middleware wrappers. You would probably want to use wrap_middleware() as well. Or use endpoint_decorator().

dmr.decorators.endpoint_decorator(original_decorator: Callable[[_ViewT], _ViewT]) → Callable[[Callable[[_ParamT], _ReturnT]], Callable[[_ParamT], _ReturnT]]

Apply regular Django-styled decorator to a single endpoint.

Use it with “raw” endpoints that return regular data, not django.http.HttpResponse.

Basically, all endpoints that can be decorated with modify().

Example:

>>> from http import HTTPStatus

>>> from dmr import Controller, HeaderSpec, modify
>>> from dmr.decorators import endpoint_decorator
>>> from dmr.plugins.pydantic import PydanticSerializer
>>> from django.contrib.auth.decorators import login_required

>>> class MyController(Controller[PydanticSerializer]):
...     @endpoint_decorator(login_required())
...     @modify(
...         extra_responses=[
...             ResponseSpec(
...                 None,
...                 status_code=HTTPStatus.FOUND,
...                 headers={'Location': HeaderSpec()},
...             ),
...         ],
...     )
...     def get(self) -> str:
...         return 'Logged in!'

It also works for things like: - django.contrib.auth.decorators.login_not_required() - django.contrib.auth.decorators.user_passes_test() - django.contrib.auth.decorators.permission_required() - django.views.decorators.debug.sensitive_post_parameters() - and any other default or custom django decorator

Warning

Be careful with decorators that you apply. They will not escape the response validation, but will return unmodified responses from the original decorators.

For example: login_required will return a redirect. You can describe it with the extra metadata.

dmr.decorators.wrap_middleware(middleware: Callable[[Callable[[...], Any]], Callable[[...], Any]], response: ResponseSpec, *responses: ResponseSpec) → Callable[[Callable[[HttpResponse], HttpResponse]], DecoratorWithResponses]

Factory function that creates a decorator with pre-configured middleware.

This allows creating reusable decorators with specific middleware and response handling.

Parameters:

• middleware – Django middleware to apply

• response – ResponseSpec for the middleware response

• responses – Others ResponseSpec

Returns:

A function that takes a converter and returns a class decorator

>>> from django.views.decorators.csrf import csrf_protect
>>> from django.http import HttpResponse
>>> from http import HTTPStatus
>>> from dmr import Controller, ResponseSpec
>>> from dmr.response import build_response
>>> from dmr.plugins.pydantic import PydanticSerializer
>>> from dmr.errors import ErrorType, ErrorModel, format_error

>>> @wrap_middleware(
...     csrf_protect,
...     ResponseSpec(
...         return_type=ErrorModel,
...         status_code=HTTPStatus.FORBIDDEN,
...     ),
... )
... def csrf_protect_json(response: HttpResponse) -> HttpResponse:
...     return build_response(
...         PydanticSerializer,
...         raw_data=format_error(
...             'CSRF verification failed. Request aborted.',
...             error_type=ErrorType.user_msg,
...         ),
...         status_code=HTTPStatus(response.status_code),
...     )

>>> @csrf_protect_json
... class MyController(Controller[PydanticSerializer]):
...     responses = [
...         *csrf_protect_json.responses,
...     ]
...
...     def post(self) -> dict[str, str]:
...         return {'message': 'ok'}

Testing

class dmr.test.DMRRequestFactory(*, json_encoder=<class 'django.core.serializers.json.DjangoJSONEncoder'>, headers=None, query_params=None, **defaults)

Test utility for testing apps using django-modern-rest.

Based on django.test.RequestFactory. See their docs for advanced usage: https://docs.djangoproject.com/en/dev/topics/testing/tools

This type, in contrast to a regular RequestFactory, sets content-type as application/json.

Sets WSGI environment.

class dmr.test.DMRAsyncRequestFactory(*, json_encoder=<class 'django.core.serializers.json.DjangoJSONEncoder'>, headers=None, query_params=None, **defaults)

Version of DMRRequestFactory but for ASGI environment.

Uses the exactly the same API.

wrap(thing)

Utility method for testing.

Pretends to wrap async controllers into async functions for typing. But in reality does nothing.

This happens due to the fact that View is typed as sync object.

class dmr.test.DMRClient(enforce_csrf_checks=False, raise_request_exception=True, *, headers=None, query_params=None, **defaults)

Test utility for testing apps using django-modern-rest.

Based on django.test.Client. See their docs for advanced usage: https://docs.djangoproject.com/en/dev/topics/testing/tools/

This type, in contrast to a regular Client, sets content-type as application/json.

class dmr.test.DMRAsyncClient(enforce_csrf_checks=False, raise_request_exception=True, *, headers=None, query_params=None, **defaults)

Async version of DMRClient.

Uses async API. Requires you to await calls to .get, .post, etc.

Auth

dmr.test.disabled_auth(controller_cls: type[Controller[BaseSerializer]], *, request: HttpRequest, user: AbstractBaseUser, auth: SyncAuth | AsyncAuth | None = None) → Generator[None]

Temporarily disable all auth for the endpoint for testing.

Parameters:

• controller_cls – Controller whose endpoint is under test.

• request – HTTP method of the endpoint to target.

• user – User to be used for this request.

• auth – Optional auth instance to be used for this request. It is set as __dmr_auth__ attribute, like our regular auth does. Use dmr.security.request_auth() to get it from request.

Added in version 0.13.0.

Throttling

dmr.test.reduced_throttling(controller_cls: type[Controller[BaseSerializer]], *, method: HTTPMethod | str, max_requests: int = 2, rate: Rate = Rate.hour, when: Literal['any', 'before_auth', 'after_auth'] = 'any') → Generator[SyncThrottle | AsyncThrottle]

Temporarily lower an endpoint’s first throttle so a test can reach it.

Replaces the first throttle of the chosen when with a copy limited to max_requests, so a few real requests trip it instead of the configured rate. Only the endpoint under test is affected; the original throttling is restored on exit. Yields the reduced throttle, whose max_requests tells you how many allowed requests to send before the next one is rejected.

The copy also has its window widened to rate, because lowering just max_requests is not enough for short windows: a 2/second throttle would reset between the driven requests and the endpoint would never be rejected. With an hour-long window every request a test sends lands inside the same window.

Parameters:

• controller_cls – Controller whose endpoint is under test.

• method – HTTP method of the endpoint to target.

• max_requests – Limit the throttle is lowered to (2 by default). The window is always widened to one hour, see above.

• rate – Time window to narrow to (hour by default).

• when – When to run the throttle – 'before_auth' (checked before auth, e.g. by IP), 'after_auth' (per-user, needs an authenticated request), or 'any' (default, the first one checked).

Added in version 0.12.0.

dmr.test.assert_throttled(response: HttpResponse, *, throttle: SyncThrottle | AsyncThrottle | None = None) → None

Assert that a response was rejected by throttling.

Collapses the repeated 429 status, header and error-body checks into a single call:

# Just the status + `ratelimit` error:
assert_throttled(response)

# Also asserts all the headers from the throttle instance exist:
assert_throttled(response, throttle=your_throttled_instance)

Parameters:

• response – The response to check.

• throttle – Throttle that rejected the request. When given, every header its providers report must be present in the response.

throttle instance defines which headers are reported depends on the header provider’s class: XRateLimit, RateLimitIETFDraft, or your own provider.

Added in version 0.12.0.

dmr.test.assert_throttling(controller_cls: type[Controller[BaseSerializer]], request_factory: Callable[[], HttpRequest], *, max_requests: int = 2, rate: Rate = Rate.hour, when: Literal['any', 'before_auth', 'after_auth'] = 'any', success_status: HTTPStatus | None = None) → tuple[HttpResponse, SyncThrottle]

Reduce the first throttle, drive requests, and assert the 429.

Sends max_requests allowed requests, then one that is rejected, and checks it with assert_throttled() – including every header the reduced throttle reports. Returns the 429 response, so you can make further assertions on it.

Parameters when and rate are passed down to reduced_throttling() and assert_throttled().

Added in version 0.12.0.

async dmr.test.assert_async_throttling(controller_cls: type[Controller[BaseSerializer]], request_factory: Callable[[], HttpRequest], *, max_requests: int = 2, rate: Rate = Rate.hour, when: Literal['any', 'before_auth', 'after_auth'] = 'any', success_status: HTTPStatus | None = None) → tuple[HttpResponse, AsyncThrottle]

Async version of assert_throttling().

Added in version 0.12.0.

Plugins

Pydantic

class dmr.plugins.pydantic.PydanticSerializer

Serialize and deserialize objects using pydantic.

Pydantic support is optional. To install it run:

pip install 'django-modern-rest[pydantic]'

to_json_kwargs

Dictionary of kwargs that will be passed to model serialization callbacks.

Type:

ClassVar[dmr.plugins.pydantic.serializer.ToJsonKwargs]

to_model_kwargs

Dictionary of kwargs that will be passed to model deserialization callbacks.

Type:

ClassVar[dmr.plugins.pydantic.serializer.ToModelKwargs]

classmethod deserialize(buffer: bytes | bytearray, *, parser: Parser, request: HttpRequest, model: Any) → Any

Convert string or bytestring to simple python object.

classmethod from_python(unstructured: Any, model: Any, *, strict: bool | None, extra_namespace: Mapping[str, Any] | None = None) → Any

Parse unstructured data from python primitives into model.

Parameters:

• unstructured – Python objects to be parsed / validated.

• model – Python type to serve as a model. Can be any type that pydantic supports. Examples: dict[str, int] and BaseModel subtypes.

• strict – Whether we use more strict validation rules. For example, it is fine for a request validation to be less strict in some cases and allow type coercition. But, response types need to be strongly validated.

• extra_namespace – Optional namespace to rebuild the type adapter. Should be used when there are forward references that pydantic cannot solve by itself.

Returns:

Structured and validated data.

Raises:

pydantic_core.ValidationError – When parsing can’t be done.

Changed in version 0.13.0: Added rebuild_namespace parameter was renamed to be extra_namespace.

optimizer

alias of PydanticEndpointOptimizer

schema_generator

alias of PydanticSchemaGenerator

classmethod serialize(structure: Any, *, renderer: Renderer) → bytes

Convert any object to raw bytestring.

classmethod serialize_hook(to_serialize: Any) → Any

Customize how some objects are serialized into simple objects.

classmethod serialize_validation_error(exc: Exception) → list[ErrorDetail]

Serialize validation error.

classmethod to_python(structured: Any) → Any

Unparse structured data from a model into Python primitives.

Parameters:

structured – Model instance.

Returns:

Unstructured data.

class dmr.plugins.pydantic.PydanticFastSerializer

Fast pydantic serializer for cases when you only work with json.

Does not use parser and renderer passed objects, does not use dmr.plugins.pyndatic.PydanticSerializer.serialize_hook and dmr.plugins.pyndatic.PydanticSerializer.deserialize_hook method.

Is built for optimizations only, use with caution.

Only works with application/json content type.

Added in version 0.6.0: See issue 830.

classmethod deserialize(buffer: bytes | bytearray, *, parser: Parser, request: HttpRequest, model: Any) → Any

Fast way to serializer pyndatic models into json bytestring.

parser parameter is always ignored.

classmethod is_supported(pluggable: Parser | Renderer) → bool

Is this parser or renderer supported?

We only support json parsers and renderers.

classmethod serialize(structure: Any, *, renderer: Renderer) → bytes

Fast way to serializer pyndatic models into json bytestring.

renderer parameter is always ignored.

class dmr.plugins.pydantic.serializer.PydanticEndpointOptimizer

Optimize endpoints that are parsed with pydantic.

classmethod optimize_endpoint(metadata: EndpointMetadata) → None

Create models for return types for validation.

class dmr.plugins.pydantic.schema.PydanticSchemaGenerator

Generates JSON schema for pydantic objects.

classmethod get_schema(model: Any, ref_template: str, *, used_for_response: bool = False) → tuple[dict[str, Any], dict[str, Any]]

Proxies the JSON schema generation to pydantic itself.

classmethod schema_name(model: Any) → str | None

Return a schema name for a model, if it exists.

final class dmr.plugins.pydantic.serializer.ToJsonKwargs

Keyword arguments for pydantic’s model dump method.

final class dmr.plugins.pydantic.serializer.ToModelKwargs

Keyword arguments for pydantic’s python object validation method.

Msgspec

class dmr.plugins.msgspec.MsgspecSerializer

Serialize and deserialize objects using msgspec.

Msgspec support is optional. To install it run:

pip install 'django-modern-rest[msgspec]'

to_json_kwargs

Dictionary of kwargs that will be passed to model serialization callbacks.

Type:

ClassVar[dmr.plugins.msgspec.serializer.ToJsonKwargs]

to_model_kwargs

Dictionary of kwargs that will be passed to model deserialization callbacks.

Type:

ClassVar[dmr.plugins.msgspec.serializer.ToModelKwargs]

classmethod deserialize(buffer: bytes | bytearray, *, parser: Parser, request: HttpRequest, model: Any) → Any

Convert string or bytestring to simple python object.

classmethod from_python(unstructured: Any, model: Any, *, strict: bool | None, extra_namespace: Mapping[str, Any] | None = None) → Any

Parse unstructured data from python primitives into model.

Parameters:

• unstructured – Python objects to be parsed / validated.

• model – Python type to serve as a model. Can be any type that msgspec supports. Examples: dict[str, int] and BaseModel subtypes.

• strict – Whether we use more strict validation rules. For example, it is fine for a request validation to be less strict in some cases and allow type coercition. But, response types need to be strongly validated.

• extra_namespace – Not used currently.

Returns:

Structured and validated data.

Raises:

msgspec.ValidationError – When parsing can’t be done.

Changed in version 0.13.0: Added extra_namespace parameter.

optimizer

alias of MsgspecEndpointOptimizer

schema_generator

alias of MsgspecSchemaGenerator

classmethod serialize(structure: Any, *, renderer: Renderer) → bytes

Convert any object to a raw bytestring.

classmethod serialize_validation_error(exc: Exception) → list[ErrorDetail]

Serialize validation error.

classmethod to_python(structured: Any) → Any

Unparse structured data from a model into Python primitives.

Parameters:

structured – Model instance.

Returns:

Unstructured data.

validation_error

alias of ValidationError

class dmr.plugins.msgspec.serializer.MsgspecEndpointOptimizer

Optimize endpoints that are parsed with Msgspec.

classmethod optimize_endpoint(metadata: EndpointMetadata) → None

Does nothing for msgspec.

class dmr.plugins.msgspec.schema.MsgspecSchemaGenerator

Generates JSON schema for msgspec objects.

classmethod get_schema(model: Any, ref_template: str, *, used_for_response: bool = False) → tuple[dict[str, Any], dict[str, Any]]

Proxies the JSON schema generation to msgspec itself.

classmethod schema_name(model: Any) → str | None

Return a schema name for a model, if it exists.

class dmr.plugins.msgspec.serializer.ToJsonKwargs

Custom deserializer API options, taken by msgspec.to_builtins().

class dmr.plugins.msgspec.serializer.ToModelKwargs

Custom serializer API options, taken by msgspec.convert().

OpenAPI

Main OpenAPI object:

class dmr.openapi.openapi.OpenAPI(*, info: Info, openapi: str, json_schema_dialect: str | None = None, servers: list[Server] | None = None, paths: dict[str, PathItem] | None = None, webhooks: dict[str, PathItem | Reference] | None = None, components: Components | None = None, security: list[dict[str, list[str]]] | None = None, tags: list[Tag] | None = None, external_docs: ExternalDocumentation | None = None)

This is the root object of the OpenAPI document.

Changed in version 0.13.0: Moved from dmr.openapi.objects.OpenAPI to dmr.openapi.openapi.OpenAPI.

convert(*, skip_validation: bool = False) → dict[str, Any]

Convert the object to OpenAPI schema dictionary.

Runs validation if 'django-modern-rest[openapi]' is installed and skip_validation is falsy.

The converted dictionary is cached on this instance and reused by subsequent calls. Finish modifying the schema before the first call and treat the returned dictionary as read-only. Build a new schema instance to reflect later changes.

Skipping validation does not prevent a later call from validating the cached dictionary.

Parts:

dmr.openapi.objects.Callback

alias of dict[str, PathItem | Reference]

class dmr.openapi.objects.Components(*, schemas: dict[str, Schema] | None = None, responses: dict[str, Response | Reference] | None = None, parameters: dict[str, Parameter | Reference] | None = None, examples: dict[str, Example | Reference] | None = None, request_bodies: dict[str, RequestBody | Reference] | None = None, headers: dict[str, Header | Reference] | None = None, security_schemes: dict[str, SecurityScheme | Reference] | None = None, links: dict[str, Link | Reference] | None = None, callbacks: dict[str, Callback | Reference] | None = None, path_items: dict[str, PathItem | Reference] | None = None)

Holds a set of reusable objects for different aspects of the OAS.

All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object.

class dmr.openapi.objects.Contact(*, name: str | None = None, url: str | None = None, email: str | None = None)

Contact information for the exposed API.

class dmr.openapi.objects.Discriminator(*, property_name: str, mapping: dict[str, str] | None = None)

Discriminator Object.

When request bodies or response payloads may be one of a number of different schemas, a discriminator object can be used to aid in serialization, deserialization, and validation. The discriminator is a specific object in a schema which is used to inform the consumer of the document of an alternative schema based on the value associated with it.

class dmr.openapi.objects.Encoding(*, content_type: str | None = None, headers: dict[str, Header | Reference] | None = None, style: str | None = None, explode: bool | None = None, allow_reserved: bool | None = None)

A single encoding definition applied to a single schema property.

class dmr.openapi.objects.Example(*, summary: str | None = None, description: str | None = None, value: Any | None = None, external_value: str | None = None)

Example Object.

In all cases, the example value is expected to be compatible with the type schema of its associated value. Tooling implementations MAY choose to validate compatibility automatically, and reject the example value(s) if incompatible.

class dmr.openapi.objects.ExternalDocumentation(*, url: str, description: str | None = None)

Allows referencing an external resource for extended documentation.

class dmr.openapi.objects.Header(*, schema: Reference | Schema | None = None, description: str | None = None, required: bool | None = None, deprecated: bool | None = None, style: str | None = None, explode: bool | None = None, example: Any | None = None, examples: dict[str, Example | Reference] | None = None, content: dict[str, MediaType] | None = None)

Header Object.

The Header Object follows the structure of the Parameter Object with the following changes: All traits that are affected by the location MUST be applicable to a location of header (for example, style).

class dmr.openapi.objects.Info(*, title: str, version: str, summary: str | None = None, description: Reference | str | None = None, terms_of_service: str | None = None, contact: Contact | None = None, license: License | None = None)

The Info object provides metadata about the API.

The metadata MAY be used by the clients if needed, and MAY be presented in editing or documentation generation tools for convenience.

class dmr.openapi.objects.License(*, name: str, identifier: str | None = None, url: str | None = None)

License information for the exposed API.

class dmr.openapi.objects.Link(*, operation_ref: str | None = None, operation_id: str | None = None, parameters: dict[str, Any] | None = None, request_body: Any | None = None, description: str | None = None, server: Server | None = None)

The Link object represents a possible design-time link for a response.

The presence of a link does not guarantee the caller’s ability to successfully invoke it, rather it provides a known relationship and traversal mechanism between responses and other operations.

final class dmr.openapi.objects.MediaTypeMetadata(*, example: Any | None = None, examples: dict[str, Example | Reference] | None = None, encoding: dict[str, Encoding] | None = None, item_encoding: Encoding | None = None, prefix_encoding: Encoding | None = None)

Media type metadata to be set on a request body.

__hash__() → int

Hash the dataclass in a safe way.

class dmr.openapi.objects.MediaType(*, schema: Reference | Schema | None = None, example: Any | None = None, examples: dict[str, Example | Reference] | None = None, encoding: dict[str, Encoding] | None = None, item_schema: Reference | Schema | None = None, item_encoding: Encoding | None = None, prefix_encoding: Encoding | None = None)

Media Type Object.

Each Media Type Object provides schema and examples for the media type identified by its key.

__post_init__() → None

Validate the object.

class dmr.openapi.objects.OAuthFlow(*, authorization_url: str | None = None, token_url: str | None = None, refresh_url: str | None = None, scopes: dict[str, str] | None = None)

Configuration details for a supported OAuth Flow.

class dmr.openapi.objects.OAuthFlows(*, implicit: OAuthFlow | None = None, password: OAuthFlow | None = None, client_credentials: OAuthFlow | None = None, authorization_code: OAuthFlow | None = None)

Allows configuration of the supported OAuth Flows.

final class dmr.openapi.objects.OpenAPIFormat(*values)

OpenAPI format.

See also

Spec: https://datatracker.ietf.org/doc/html/draft-bhutton-json-schema-validation-00#page-13

final class dmr.openapi.objects.OpenAPIType(*values)

OpenAPI types.

class dmr.openapi.objects.Operation(*, tags: list[str] | None = None, summary: str | None = None, description: str | None = None, external_docs: ExternalDocumentation | None = None, operation_id: str | None = None, parameters: list[Parameter | Reference] | None = None, request_body: RequestBody | Reference | None = None, responses: Responses | None = None, callbacks: dict[str, Callback | Reference] | None = None, deprecated: bool = False, security: list[SecurityRequirement] | None = None, servers: list[Server] | None = None)

Describes a single API operation on a path.

class dmr.openapi.objects.ParameterMetadata(*, description: str | None = None, deprecated: bool = False, allow_empty_value: bool | None = None, style: str | None = None, explode: bool | None = None, allow_reserved: bool | None = None, example: Any | None = None, examples: dict[str, Example | Reference] | None = None)

Describes metadata for a single operation parameter.

class dmr.openapi.objects.Parameter(*, description: str | None = None, deprecated: bool = False, allow_empty_value: bool | None = None, style: str | None = None, explode: bool | None = None, allow_reserved: bool | None = None, example: Any | None = None, examples: dict[str, Example | Reference] | None = None, name: str, param_in: Annotated[str, FieldInfo(annotation=NoneType, required=True, alias='in', alias_priority=2)], schema: Reference | Schema | None = None, content: dict[str, MediaType] | None = None, required: bool = False)

Bases: ParameterMetadata

Describes a single operation parameter.

class dmr.openapi.objects.PathItem(*, ref: Annotated[str | None, FieldInfo(annotation=NoneType, required=True, alias='$ref', alias_priority=2)] = None, summary: str | None = None, description: str | None = None, get: Operation | None = None, put: Operation | None = None, post: Operation | None = None, delete: Operation | None = None, options: Operation | None = None, head: Operation | None = None, patch: Operation | None = None, trace: Operation | None = None, query: Operation | None = None, servers: list[Server] | None = None, parameters: list[Parameter | Reference] | None = None, additional_operations: dict[str, Operation] | None = None)

Describes the operations available on a single path.

A Path Item MAY be empty, due to ACL constraints. The path itself is still exposed to the documentation viewer but they will not know which operations and parameters are available.

classmethod split_operations(operations: dict[str, Operation]) → tuple[dict[str, Any], dict[str, Operation] | None]

Split operations into standard HTTP methods and custom ones.

dmr.openapi.objects.Paths

alias of dict[str, PathItem]

class dmr.openapi.objects.Reference(*, ref: Annotated[str, FieldInfo(annotation=NoneType, required=True, alias='$ref', alias_priority=2)], summary: str | None = None, description: str | None = None)

A simple object to allow referencing other components in the document.

The $ref string value contains a URI RFC3986, which identifies the location of the value being referenced.

class dmr.openapi.objects.RequestBody(*, content: dict[str, MediaType], description: str | None = None, required: bool = True)

Describes a single request body.

class dmr.openapi.objects.Response(*, description: str | None = None, headers: dict[str, Header | Reference] | None = None, content: dict[str, MediaType] | None = None, links: dict[str, Link | Reference] | None = None)

Describes a single response from an API Operation.

Including design-time, static links to operations based on the response.

dmr.openapi.objects.Responses

alias of dict[str, Response | Reference]

class dmr.openapi.objects.Schema(*, all_of: list[Reference | Schema] | None = None, any_of: list[Reference | Schema] | None = None, one_of: list[Reference | Schema] | None = None, schema_not: Annotated[Reference | Schema | None, FieldInfo(annotation=NoneType, required=True, alias='not', alias_priority=2)] = None, schema_if: Annotated[Reference | Schema | None, FieldInfo(annotation=NoneType, required=True, alias='if', alias_priority=2)] = None, schema_then: Annotated[Reference | Schema | None, FieldInfo(annotation=NoneType, required=True, alias='then', alias_priority=2)] = None, schema_else: Annotated[Reference | Schema | None, FieldInfo(annotation=NoneType, required=True, alias='else', alias_priority=2)] = None, dependent_schemas: dict[str, Reference | Schema] | None=None, prefix_items: list[Reference | Schema] | None = None, items: Reference | Schema | bool | None = None, contains: Reference | Schema | None = None, properties: dict[str, Reference | Schema] | None=None, pattern_properties: dict[str, Reference | Schema] | None=None, additional_properties: Reference | Schema | bool | None = None, property_names: Reference | Schema | None = None, unevaluated_items: Reference | Schema | None = None, unevaluated_properties: Reference | Schema | None = None, type: OpenAPIType | list[OpenAPIType] | None = None, enum: list[Any] | None = None, const: Any | None = None, multiple_of: float | None = None, maximum: float | None = None, exclusive_maximum: float | None = None, minimum: float | None = None, exclusive_minimum: float | None = None, max_length: int | None = None, min_length: int | None = None, pattern: str | None = None, max_items: int | None = None, min_items: int | None = None, unique_items: bool | None = None, max_contains: int | None = None, min_contains: int | None = None, max_properties: int | None = None, min_properties: int | None = None, required: list[str] = <factory>, dependent_required: dict[str, list[str]] | None=None, format: OpenAPIFormat | None = None, content_encoding: str | None = None, content_media_type: str | None = None, content_schema: Reference | Schema | None = None, title: str | None = None, description: str | None = None, default: Any | None = None, deprecated: bool | None = None, read_only: bool | None = None, write_only: bool | None = None, examples: list[Any] | None = None, discriminator: Discriminator | None = None, xml: XML | None = None, external_docs: ExternalDocumentation | None = None, example: Any | None = None, dynamic_anchor: Annotated[str | None, FieldInfo(annotation=NoneType, required=True, alias='$dynamicAnchor', alias_priority=2)] = None, dynamic_ref: Annotated[str | None, FieldInfo(annotation=NoneType, required=True, alias='$dynamicRef', alias_priority=2)] = None, ref: Annotated[str | None, FieldInfo(annotation=NoneType, required=True, alias='$ref', alias_priority=2)] = None, anchor: Annotated[str | None, FieldInfo(annotation=NoneType, required=True, alias='$anchor', alias_priority=2)] = None, comment: Annotated[str | None, FieldInfo(annotation=NoneType, required=True, alias='$comment', alias_priority=2)] = None, schema_uri: Annotated[str | None, FieldInfo(annotation=NoneType, required=True, alias='$schema', alias_priority=2)] = None, defs: Annotated[dict[str, Reference | Schema] | None, FieldInfo(annotation=NoneType, required=True, alias='$defs', alias_priority=2)] = None)

The Schema Object allows the definition of input and output data types.

These types can be objects, but also primitives and arrays. Unless stated otherwise, the property definitions follow those of JSON Schema and do not add any additional semantics. Where JSON Schema indicates that behavior is defined by the application (e.g. for annotations), OAS also defers the definition of semantics to the application consuming the OpenAPI document.

dmr.openapi.objects.SecurityRequirement

alias of dict[str, list[str]]

class dmr.openapi.objects.SecurityScheme(*, type: Literal['apiKey', 'http', 'mutualTLS', 'oauth2', 'openIdConnect'], description: str | None = None, name: str | None = None, security_scheme_in: Annotated[Literal['query', 'header', 'cookie'] | None, FieldInfo(annotation=NoneType, required=True, alias='in', alias_priority=2)] = None, scheme: str | None = None, bearer_format: str | None = None, flows: OAuthFlows | None = None, open_id_connect_url: str | None = None)

Defines a security scheme that can be used by the operations.

Supported schemes are HTTP authentication, an API key (either as a header, a cookie parameter or as a query parameter), mutual TLS (use of a client certificate), OAuth2’s common flows (implicit, password, client credentials and authorization code) as defined in RFC6749, and OpenID Connect Discovery. Please note that as of 2020, the implicit flow is about to be deprecated by OAuth 2.0 Security Best Current Practice. Recommended for most use cases is Authorization Code Grant flow with PKCE.

class dmr.openapi.objects.Server(*, url: str, description: str | None = None, variables: dict[str, ServerVariable] | None = None)

An object representing a Server.

class dmr.openapi.objects.ServerVariable(*, default: str, enum: list[str] | None = None, description: str | None = None)

An object representing a Server Variable for server URL template.

class dmr.openapi.objects.Tag(*, name: str, description: str | None = None, external_docs: ExternalDocumentation | None = None)

Adds metadata to a single tag that is used by the Operation object.

It is not mandatory to have a Tag object per tag defined in the Operation object instances.

class dmr.openapi.objects.XML(*, name: str | None = None, namespace: str | None = None, prefix: str | None = None, attribute: bool = False, wrapped: bool = False)

A metadata object that allows for more fine-tuned XML model definitions.

When using arrays, XML element names are not inferred (for singular/plural forms) and the name property SHOULD be used to add that information.

OpenAPI Core

class dmr.openapi.core.merger.ConfigMerger(context: OpenAPIContext)

Merges OpenAPI configuration with generated paths and components.

This class is responsible for combining the OpenAPI configuration from the context with the generated paths and components to create a complete OpenAPI specification object.

__call__(paths: dict[str, PathItem], components: Components) → OpenAPI

Merge paths and components with configuration.

class dmr.openapi.core.registry.OperationIdRegistry

Registry for OpenAPI operation IDs.

register(operation_id: str) → None

Register an operation ID in the registry.

class dmr.openapi.core.registry.SchemaRegistry

Registry for Schemas.

get_reference(schema_name: str | None, annotation: Any | sentinel = EMPTY) → Reference | None

Get registered reference.

maybe_resolve_reference(reference: Reference | Schema, *, resolution_context: dict[str, Schema] | None = None) → Schema

Resolve reference and return a schema back.

register(schema_name: str, schema: Schema, annotation: Any | sentinel = EMPTY) → Reference

Register Schema in registry.

property schemas: dict[str, Schema]

Return schemas by name.

try_unregister(schema_name: str | None) → None

Try to unregister the schema by name.

class dmr.openapi.core.registry.SchemaCallback(*args, **kwargs)

Callback protocol for the schema registration.

__call__(annotation: Any, origin: Any, type_args: Any, *, used_for_response: bool, skip_registration: bool) → Reference | Schema | None

Resolve the annotation into schema or into a reference.

Return None to fallback to the default resolution.

OpenAPI Generators

class dmr.openapi.generators.ComponentParserGenerator(_context: OpenAPIContext)

Generator for OpenAPI Parameter objects.

__call__(operation_id: str, pattern: URLPattern, metadata: EndpointMetadata, serializer: type[BaseSerializer]) → tuple[RequestBody | Reference | None, list[Parameter | Reference] | None]

Generate parameters from parsers.

class dmr.openapi.generators.ResponseGenerator(_context: OpenAPIContext)

Generator for OpenAPI Response objects.

__call__(metadata: EndpointMetadata, serializer: type[BaseSerializer]) → dict[str, Response | Reference]

Generate responses from response specs.

get_schema(response_spec: ResponseSpec, metadata: EndpointMetadata, serializer: type[BaseSerializer], context: OpenAPIContext, *, schema_field_name: Literal['schema', 'item_schema'] = 'schema', used_for_response: bool = True) → Response

Returns the OpenAPI schema for the response.

Can be customized in ResponseSpec subclasses.

class dmr.openapi.generators.SchemaGenerator(_context: OpenAPIContext)

Generate OpenAPI schemas from different type annotations.

__call__(annotation: Any, serializer: type['BaseSerializer'], *, used_for_response: bool = False, skip_registration: Literal[True], register_referenced_components: bool = False) → Schema

__call__(annotation: Any, serializer: type['BaseSerializer'], *, used_for_response: bool = False, skip_registration: bool = False, register_referenced_components: bool = False) → Reference | Schema

Get schema for an annotation.

Here’s the algorithm we use:

1. First, we try to find manually defined overrides for the annotation

2. If nothing is found, we try to find any existing schema references

3. Next, we try to get a model schema from a serializer. If it exists, we create an internal reference and return it. The next time it will be returned as a reference, cached.

4. If nothing worked, we raise an error

Raises:

UnsolvableAnnotationsError – when we can’t generate an OpenAPI schema from an existing annotation.

class dmr.openapi.generators.SecuritySchemeGenerator(_context: OpenAPIContext)

Generator for OpenAPI Security Schemes.

Responsible for processing authentication providers, extracting their security schemes, registering them in the context, and returning the corresponding security requirements for the operation.

__call__(auth_providers: Sequence[SyncAuth | AsyncAuth] | None, serializer: type[BaseSerializer]) → list[SecurityRequirement] | None

Process auth providers and generate security requirements.

Iterates over the provided authentication providers, registers their security schemes in the global registry, and collects their security usage requirements.

class dmr.openapi.generators.OperationIdGenerator(_context: OpenAPIContext)

Generator for unique OpenAPI operation IDs.

The Operation ID builder is responsible for creating unique operation IDs for OpenAPI operations. It uses the explicit operation_id from endpoint metadata if available, otherwise generates one from the HTTP method and path following RFC 3986 specifications. All generated operation IDs are registered in the registry to ensure uniqueness across the OpenAPI specification.

__call__(path: str, suffix: str, metadata: EndpointMetadata, serializer: type[BaseSerializer]) → str

Generate a unique operation ID for an OpenAPI operation.

Uses the explicit operation_id from endpoint metadata if available, otherwise generates one from the HTTP method and path. The operation ID is registered in the registry to ensure uniqueness.

Existing OpenAPI views

Existing implementations:

class dmr.openapi.views.ScalarView(**kwargs)

View for rendering the OpenAPI schema with Scalar.

Renders an interactive HTML page that allows exploring the OpenAPI specification using Scalar API Reference.

content_type

Content type of the rendered response. Defaults to "text/html".

Type:

ClassVar[str]

template_name

Template used to render the Scalar page.

Type:

ClassVar[str]

get(request: HttpRequest) → HttpResponse

Render the OpenAPI schema using Scalar template.

class dmr.openapi.views.SwaggerView(**kwargs)

View for rendering the OpenAPI schema with Swagger UI.

Renders an interactive HTML page that allows exploring the OpenAPI specification using Swagger UI components.

content_type

Content type of the rendered response. Defaults to "text/html".

Type:

ClassVar[str]

template_name

Template used to render the Swagger UI page.

Type:

ClassVar[str]

get(request: HttpRequest) → HttpResponse

Render the OpenAPI schema using Swagger template.

class dmr.openapi.views.RedocView(**kwargs)

View for rendering the OpenAPI schema with Redoc.

Renders an interactive HTML page that allows exploring the OpenAPI specification using Redoc components.

content_type

Content type of the rendered response. Defaults to "text/html".

Type:

ClassVar[str]

template_name

Template used to render the Redoc page.

Type:

ClassVar[str]

get(request: HttpRequest) → HttpResponse

Render the OpenAPI schema using Redoc template.

class dmr.openapi.views.StoplightView(**kwargs)

View for rendering the OpenAPI schema with Stoplight.

Renders an interactive HTML page that allows exploring the OpenAPI specification using Stoplight API Reference.

content_type

Content type of the rendered response. Defaults to "text/html".

Type:

ClassVar[str]

template_name

Template used to render the Stoplight page.

Type:

ClassVar[str]

get(request: HttpRequest) → HttpResponse

Render the OpenAPI schema using Stoplight template.

class dmr.openapi.views.OpenAPIJsonView(**kwargs)

View for returning the OpenAPI schema as JSON.

Produces a JSON representation of the OpenAPI specification that can be used by API documentation tools and client code generators.

content_type

Content type of the rendered response. Defaults to "application/json".

Type:

ClassVar[str]

get(request: HttpRequest) → HttpResponse

Render the OpenAPI schema as JSON response.

class dmr.openapi.views.yaml.OpenAPIYamlView(**kwargs)

View for returning the OpenAPI schema as YAML.

This view mirrors OpenAPIJsonView, but renders the converted schema using pyyaml. Produces a YAML representation of the OpenAPI specification that can be used by API documentation tools and client code generators.

get(request: HttpRequest) → HttpResponse

Render the OpenAPI schema as YAML response.

Base classes:

class dmr.openapi.views.base.OpenAPIView(**kwargs)

Base view for serving an OpenAPI schema.

This view extends Django’s View to accept an OpenAPI instance via as_view(). The passed schema is stored on the view class and can be rendered in any concrete subclass (for example, as JSON or YAML).

classmethod as_view(schema: OpenAPI, *, skip_validation: bool = False, **initkwargs: Any) → Callable[[...], HttpResponseBase]

Create a view function bound to the given OpenAPI schema.

property schema: OpenAPI

Return the OpenAPI schema bound to this view instance.

The schema is injected via as_view() and stored internally in the private _schema attribute. This property provides a typed and safe accessor for that value.

property skip_validation: bool

Return whether or not we should skip validation for this view.