Decorators

pydantictornado.api.add_error_response(status_code, **kwargs)

Document an error returned from an operation.

Stack this decorator with api.expose_operation to document that an operation returns a specific status code. THe status code and other parameters are added to the OpenAPI responses section for the decorated operation.

This decorator works in conjunction with the register_error_model method of the application instance. You should bind the error model and status code in the application instance when the same model is used across many handlers. Including the model parameter in this decorator is optional and will override any model registered in the application instance.

Parameters:

• status_code (int) –

  The HTTP status code of the error response.

• model –

  The Pydantic model that describes the error response body.

• description –

  A description of the error response.

pydantictornado.api.add_response_header(name, **kwargs)

Describe a response header returned from a decorated operation.

This decorator adds a response header with the provided definition with a decorated operation. Most of the parameters are copied as-is into the OpenAPI specification. The model parameter should be included for complex header definitions that have a specific structure.

The for_status parameter can be used to limit the header to specific response status codes. If omitted, the header is included for all status codes.

Parameters:

• name (str) –

  The name of the response header

• description –

  A description of the header.

• model –

  The Pydantic model that describes the header value.

• required –

  Is the header always returned?

• explode –

  Are multiple values be represented as separate parameters?

• deprecated –

  Is this header deprecated?

• for_status –

  Status codes for which this header is returned.

pydantictornado.api.expose_operation(*args, **kwargs)

expose_operation(
    **kwargs: typing.Unpack[ExplicitOpenAPIDocumentation],
) -> typing.Callable[
    [
        typing.Callable[
            ..., typing.Awaitable[pydantic.BaseModel | None]
        ]
    ],
    RequestMethod,
]

expose_operation(
    some_args: str,
    /,
    **kwargs: typing.Unpack[ExplicitOpenAPIDocumentation],
) -> typing.Callable[
    [
        typing.Callable[
            ..., typing.Awaitable[pydantic.BaseModel | None]
        ]
    ],
    RequestMethod,
]

expose_operation(
    func: typing.Callable[
        ..., typing.Awaitable[ModelType | None]
    ],
    /,
    **kwargs: typing.Unpack[ExplicitOpenAPIDocumentation],
) -> RequestMethod

Exposes an operation to be used as an endpoint in an HTTP framework.

This decorator is used to expose a function as an HTTP endpoint in the OpenAPI specification. The decorated method must be a coroutine that receives the deserialized request body as a parameter and returns the response as a Pydantic model instance. The decorator returns a wrapper function that uses the standard Tornado RequestHandler signature.

When the wrapper method is invoked, it converts request.body to a Pydantic model instance and passes it to the decorated method. Path parameters are passed as positional arguments after being coerced to the appropriate type. The return value from the method is serialized as JSON and written to the response.

@api.expose_operation
async def post(
    self, item_id: int, *,
    body: typing.Annotated[CreataRequest, api.Body]
) -> Item: ...

The decorator takes care of the following tasks for you:

1. Extracts the request body from the request and converts it to a CreateRequest instance. The body parameter is identified by adding an api.Body annotation.
2. Converts the item_id path parameter from a string to an integer
3. Invokes the post method with the converted arguments
4. Converts the Item return value to a JSON string and writes it as the response
5. Captures Pydantic errors and returns an appropriate response

In addition to transforming the request and response, the operation is added to the OpenAPI specification based on how it is registered in the application router. Additional OpenAPI properties can be supplied as keyword arguments to the decorator. See ExplicitOpenAPIDocumentation for a list of supported properties.

Raises:

• BodyValidationError –

  Occurs during request validation if the body does not match the Pydantic model attribute's validation rules.

• MarkerNotFoundError –

  Occurs when the OpenAPI marker is not found on the provided function but additional OpenAPI metadata needs to be attached.

• ParameterUsageError –

  Raised when multiple body parameters are detected.

• TypeError –

  Raised when the provided arguments do not conform to the expected types (e.g., non-callable or non-coroutine function passed as the first argument).

• UnsupportedAnnotationError –

  Raised when an unsupported type is provided for a parameter annotation, such as missing type annotations or an unsupported special form.