tatami.endpoint 🧭¶

This module contains decorators like @get, @post, @put, and others that are used to define HTTP endpoints inside router classes. These decorators map class methods to specific HTTP methods and subpaths.

class tatami.endpoint.BoundEndpoint(endpoint, instance)[source]¶

Bases: TatamiObject

Parameters:: endpoint (Endpoint)

__init__(endpoint, instance)[source]¶

Parameters:: endpoint (Endpoint)

property deprecated: bool¶

property docs: str¶

property endpoint_function¶

get_route()[source]¶

Return type:: Route

property request_type: Request | BaseModel | None¶

property response_type: Type[Response] | Type[BaseModel] | None¶

async run(request)[source]¶

Handle an incoming HTTP request by extracting path parameters, query parameters, headers, and request body based on function annotations, invoking the endpoint function, and returning an appropriate response.

The method: - Extracts path parameters from the request URL. - Extracts query parameters from the request query string. - Extracts headers from the request headers. - For POST, PUT, or PATCH methods, attempts to parse the JSON body and instantiate Pydantic models defined in function annotations. - Validates all parameters against their type annotations. - Calls the endpoint function (self.ep_fn) with the app instance and all extracted parameters. - Awaits the result if it is awaitable. - Wraps the result in a response using self.response_type if defined, otherwise uses a default wrapper.

Parameters:: request (Request) – The incoming HTTP request object.
Returns:: A Starlette Response instance, either directly returned or awaited.
Return type:: Union[Response, Awaitable[Response]]

Usage example:

# Assume `endpoint` is an instance with `run` method,
# and `request` is a Starlette Request object.

response = await endpoint.run(request)
# `response` is a Starlette Response object ready to be sent back to the client.

property signature: Signature¶

property summary: str¶

property tags: list[str]¶

class tatami.endpoint.Endpoint(method, func, path=None, request_type=None, response_type=None, tags=None)[source]¶

Bases: TatamiObject

Parameters:

method (str)
func (Callable)
path (str)
request_type (Type[Request] | Type[BaseModel] | None)
response_type (Type[Response] | None)
tags (list[str] | None)

__init__(method, func, path=None, request_type=None, response_type=None, tags=None)[source]¶

Parameters:

method (str)
func (Callable)
path (str)
request_type (Type[Request] | Type[BaseModel] | None)
response_type (Type[Response] | None)
tags (list[str] | None)

property deprecated: bool¶

tatami.endpoint.delete(func: F) → F[source]¶
tatami.endpoint.delete(path: str, *, response_type: Type[Response] | None = None) → Callable[[F], F]
tatami.endpoint.delete(*, response_type: Type[Response] | None = None) → Callable[[F], F]

tatami.endpoint.get(func: F) → F[source]¶

tatami.endpoint.get(path: str, *, response_type: Type[Response] | None = None) → Callable[[F], F]

tatami.endpoint.get(*, response_type: Type[Response] | None = None) → Callable[[F], F]

Registers a function as a GET endpoint. This decorator supports multiple forms:

@get: Registers the endpoint at the parent router’s path.
@get(“/subpath”): Registers the endpoint at a subpath relative to the parent router.
@get(response_type=”json”): Registers at the parent path with a specified response type.
@get(“/subpath”, response_type=”json”): Registers at a subpath with response type metadata.

The full route is composed by joining the parent router’s path with the provided subpath.

Parameters:

path_or_func – A subpath string (starting with ‘/’) or the function to decorate. If omitted, the endpoint is registered at the parent router’s path.
**kwargs – Optional metadata such as response_type.

Returns:

Either the original function or a decorator that wraps it.

tatami.endpoint.head(func: F) → F[source]¶
tatami.endpoint.head(path: str, *, response_type: Type[Response] | None = None) → Callable[[F], F]
tatami.endpoint.head(*, response_type: Type[Response] | None = None) → Callable[[F], F]

tatami.endpoint.options(func: F) → F[source]¶
tatami.endpoint.options(path: str, *, response_type: Type[Response] | None = None) → Callable[[F], F]
tatami.endpoint.options(*, response_type: Type[Response] | None = None) → Callable[[F], F]

tatami.endpoint.patch(func: F) → F[source]¶
tatami.endpoint.patch(path: str, *, response_type: Type[Response] | None = None) → Callable[[F], F]
tatami.endpoint.patch(*, response_type: Type[Response] | None = None) → Callable[[F], F]

tatami.endpoint.post(func: F) → F[source]¶
tatami.endpoint.post(path: str, *, response_type: Type[Response] | None = None) → Callable[[F], F]
tatami.endpoint.post(*, response_type: Type[Response] | None = None) → Callable[[F], F]

tatami.endpoint.put(func: F) → F[source]¶
tatami.endpoint.put(path: str, *, response_type: Type[Response] | None = None) → Callable[[F], F]
tatami.endpoint.put(*, response_type: Type[Response] | None = None) → Callable[[F], F]

tatami.endpoint.request(method: Literal['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'], func: F) → F[source]¶

tatami.endpoint.request(method: Literal['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'], path: str, *, response_type: Type[Response] | None = None) → Callable[[F], F]

tatami.endpoint.request(method: Literal['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS'], *, response_type: Type[Response] | None = None) → Callable[[F], F]

Convenience factory function to create an Endpoint instance with the given HTTP method and path. Meant to be used as a decorator.

Parameters:

method (str) – The HTTP method for the endpoint (e.g., ‘GET’, ‘POST’, ‘PUT’, etc.).
path (str) – The URL path pattern for the endpoint (e.g., ‘/users/{user_id}’).
response_type (Optional[Type[Response]]) – Optional Starlette Response subclass to use for responses.

Returns:

An instance of Endpoint initialized with the specified method, path, and response type.

Return type:

Endpoint

Usage example:

@request('GET', '/users/{user_id}', response_type=JSONResponse)
def get_user_by_id(self, user_id):
    ...