Responses ========= Litestar allows for several ways in which HTTP responses can be specified and handled, each fitting a different use case. The base pattern though is straightforward - simply return a value from a route handler function and let Litestar take care of the rest: .. code-block:: python from pydantic import BaseModel from litestar import get class Resource(BaseModel): id: int name: str @get("/resources") def retrieve_resource() -> Resource: return Resource(id=1, name="my resource") In the example above, the route handler function returns an instance of the ``Resource`` pydantic class. This value will then be used by Litestar to construct an instance of the :class:`Response ` class using defaults values: the response status code will be set to ``200`` and it's ``Content-Type`` header will be set to ``application/json``. The ``Resource`` instance will be serialized into JSON and set as the response body. Media Type ---------- You do not have to specify the ``media_type`` kwarg in the route handler function if the response should be JSON. But if you wish to return a response other than JSON, you should specify this value. You can use the :class:`MediaType ` enum for this purpose: .. code-block:: python from litestar import MediaType, get @get("/resources", media_type=MediaType.TEXT) def retrieve_resource() -> str: return "The rumbling rabbit ran around the rock" The value of the ``media_type`` kwarg affects both the serialization of response data and the generation of OpenAPI docs. The above example will cause Litestar to serialize the response as a simple bytes string with a ``Content-Type`` header value of ``text/plain``. It will also set the corresponding values in the OpenAPI documentation. MediaType has the following members: * MediaType.JSON: ``application/json`` * MediaType.MessagePack: ``application/x-msgpack`` * MediaType.TEXT: ``text/plain`` * MediaType.HTML: ``text/html`` You can also set any `IANA referenced `_ media type string as the ``media_type``. While this will still affect the OpenAPI generation as expected, you might need to handle serialization using either a :ref:`custom response ` with serializer or by serializing the value in the route handler function. JSON responses ++++++++++++++ As previously mentioned, the default ``media_type`` is ``MediaType.JSON``. which supports the following values: * :doc:`dataclasses ` * `pydantic dataclasses `_ * `pydantic models `_ * models from libraries that extend pydantic models * :class:`UUIDs ` * :doc:`datetime objects ` * `msgspec.Struct `_ * container types such as :class:`dict` or :class:`list` containing supported types If you need to return other values and would like to extend serialization you can do this :ref:`custom responses `. You can also set an application media type string with the ``+json`` suffix defined in `RFC 6839 `_ as the ``media_type`` and it will be recognized and serialized as json. For example, you can use ``application/vnd.example.resource+json`` and it will work just like json but have the appropriate content-type header and show up in the generated OpenAPI schema. .. literalinclude:: /examples/responses/json_suffix_responses.py :language: python MessagePack responses +++++++++++++++++++++ In addition to JSON, Litestar offers support for the `MessagePack `_ format which can be a time and space efficient alternative to JSON. It supports all the same types as JSON serialization. To send a ``MessagePack`` response, simply specify the media type as ``MediaType.MESSAGEPACK``\ : .. code-block:: python from typing import Dict from litestar import get, MediaType @get(path="/health-check", media_type=MediaType.MESSAGEPACK) def health_check() -> Dict[str, str]: return {"hello": "world"} Plaintext responses +++++++++++++++++++ For ``MediaType.TEXT``, route handlers should return a :class:`str` or :class:`bytes` value: .. code-block:: python from litestar import get, MediaType @get(path="/health-check", media_type=MediaType.TEXT) def health_check() -> str: return "healthy" HTML responses ++++++++++++++ For ``MediaType.HTML``, route handlers should return a :class:`str` or :class:`bytes` value that contains HTML: .. code-block:: python from litestar import get, MediaType @get(path="/page", media_type=MediaType.HTML) def health_check() -> str: return """
Hello World!
""" .. tip:: It's a good idea to use a :ref:`template engine ` for more complex HTML responses and to write the template itself in a separate file rather than a string. Content Negotiation ------------------- If your handler can return data with different media types and you want to use `Content Negotiation `_ to allow the client to choose which type to return, you can use the :attr:`Request.accept ` property to calculate the best matching return media type. .. literalinclude:: /examples/responses/response_content.py :language: python Status Codes ------------ You can control the response ``status_code`` by setting the corresponding kwarg to the desired value: .. code-block:: python from pydantic import BaseModel from litestar import get from litestar.status_codes import HTTP_202_ACCEPTED class Resource(BaseModel): id: int name: str @get("/resources", status_code=HTTP_202_ACCEPTED) def retrieve_resource() -> Resource: return Resource(id=1, name="my resource") If ``status_code`` is not set by the user, the following defaults are used: * POST: 201 (Created) * DELETE: 204 (No Content) * GET, PATCH, PUT: 200 (Ok) .. attention:: For status codes < 100 or 204, 304 statuses, no response body is allowed. If you specify a return annotation other than ``None``, an :class:`ImproperlyConfiguredException ` will be raised. .. note:: When using the ``route`` decorator with multiple http methods, the default status code is ``200``. The default for ``delete`` is ``204`` because by default it is assumed that delete operations return no data. This though might not be the case in your implementation - so take care of setting it as you see fit. .. tip:: While you can write integers as the value for ``status_code``, e.g. ``200``, it's best practice to use constants (also in tests). Litestar includes easy to use statuses that are exported from ``litestar.status_codes``, e.g. ``HTTP_200_OK`` and ``HTTP_201_CREATED``. Another option is the :class:`http.HTTPStatus` enum from the standard library, which also offers extra functionality. Returning responses ------------------- While the default response handling fits most use cases, in some cases you need to be able to return a response instance directly. Litestar allows you to return any class inheriting from the :class:`Response ` class. Thus, the below example will work perfectly fine: .. literalinclude:: /examples/responses/returning_responses.py :language: python .. attention:: In the case of the builtin :class:`Template `, :class:`File `, :class:`Stream `, and :class:`Redirect ` you should use the response "response containers", otherwise OpenAPI documentation will not be generated correctly. For more details see the respective documentation sections: - `Template responses`_ - `File responses`_ - `Streaming responses`_ - `Redirect responses`_ Annotating responses ++++++++++++++++++++ As you can see above, the :class:`Response ` class accepts a generic argument. This allows Litestar to infer the response body when generating the OpenAPI docs. .. note:: If the generic argument is not provided, and thus defaults to ``Any``, the OpenAPI docs will be imprecise. So make sure to type this argument even when returning an empty or ``null`` body, i.e. use ``None``. Returning ASGI Applications +++++++++++++++++++++++++++ Litestar also supports returning ASGI applications directly, as you would responses. For example: .. code-block:: python from litestar import get from litestar.types import ASGIApp, Receive, Scope, Send @get("/") def handler() -> ASGIApp: async def my_asgi_app(scope: Scope, receive: Receive, send: Send) -> None: ... return my_asgi_app What is an ASGI Application? ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ An ASGI application in this context is any async callable (function, class method or simply a class that implements that special :meth:`object.__call__` dunder method) that accepts the three ASGI arguments: ``scope``, ``receive``, and ``send``. For example, all the following examples are ASGI applications: Function ASGI Application ~~~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: python from litestar.types import Receive, Scope, Send async def my_asgi_app_function(scope: Scope, receive: Receive, send: Send) -> None: # do something here ... Method ASGI Application ~~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: python from litestar.types import Receive, Scope, Send class MyClass: async def my_asgi_app_method( self, scope: Scope, receive: Receive, send: Send ) -> None: # do something here ... Class ASGI Application ~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: python from litestar.types import Receive, Scope, Send class ASGIApp: async def __call__(self, scope: Scope, receive: Receive, send: Send) -> None: # do something here ... Returning responses from third party libraries ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Because you can return any ASGI Application from a route handler, you can also use any ASGI application from other libraries. For example, you can return the response classes from Starlette or FastAPI directly from route handlers: .. code-block:: python from starlette.responses import JSONResponse from litestar import get from litestar.types import ASGIApp @get("/") def handler() -> ASGIApp: return JSONResponse(content={"hello": "world"}) # type: ignore .. attention:: Litestar offers strong typing for the ASGI arguments. Other libraries often offer less strict typing, which might cause type checkers to complain when using ASGI apps from them inside Litestar. For the time being, the only solution is to add ``# type: ignore`` comments in the pertinent places. Nonetheless, the above example will work perfectly fine. Setting Response Headers ------------------------- Litestar allows you to define response headers by using the ``response_headers`` kwarg. This kwarg is available on all layers of the app - individual route handlers, controllers, routers, and the app itself: .. literalinclude:: /examples/responses/response_headers_1.py :language: python In the above example the response returned from ``my_route_handler`` will have headers set from each layer of the application using the given key+value combinations. I.e. it will be a dictionary equal to this: .. code-block:: json { "my-local-header": "local header", "controller-level-header": "controller header", "router-level-header": "router header", "app-level-header": "app header" } The respective descriptions will be used for the OpenAPI documentation. .. tip:: :class:`ResponseHeader ` is a special class that allows to add OpenAPI attributes such as `description` or `documentation_only`. If you don't need those, you can optionally define `response_headers` using a mapping - such as a dictionary - as well: .. code-block:: python @get(response_headers={"my-header": "header-value"}) async def handler() -> str: ... Setting Headers Dynamically +++++++++++++++++++++++++++ The above detailed scheme works great for statically configured headers, but how would you go about handling dynamically setting headers? Litestar allows you to set headers dynamically in several ways and below we will detail the two primary patterns. Using Annotated Responses ^^^^^^^^^^^^^^^^^^^^^^^^^ We can simply return a response instance directly from the route handler and set the headers dictionary manually as you see fit, e.g.: .. literalinclude:: /examples/responses/response_headers_2.py :language: python In the above we use the ``response_headers`` kwarg to pass the ``name`` and ``description`` parameters for the ``Random-Header`` to the OpenAPI documentation, but we set the value dynamically in as part of the :ref:`annotated response ` we return. To this end we do not set a ``value`` for it and we designate it as ``documentation_only=True``. Using the After Request Hook ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ An alternative pattern would be to use an :ref:`after request handler `. We can define the handler on different layers of the application as explained in the pertinent docs. We should take care to document the headers on the corresponding layer: .. literalinclude:: /examples/responses/response_headers_3.py :language: python In the above we set the response header using an ``after_request_handler`` function on the router level. Because the handler function is applied on the router, we also set the documentation for it on the router. We can use this pattern to fine-tune the OpenAPI documentation more granularly by overriding header specification as required. For example, lets say we have a router level header being set and a local header with the same key but a different value range: .. literalinclude:: /examples/responses/response_headers_4.py :language: python Predefined Headers ++++++++++++++++++ Litestar has a dedicated implementation for a few commonly used headers. These headers can be set separately with dedicated keyword arguments or as class attributes on all layers of the app (individual route handlers, controllers, routers, and the app itself). Each layer overrides the layer above it - thus, the headers defined for a specific route handler will override those defined on its router, which will in turn override those defined on the app level. These header implementations allow easy creating, serialization and parsing according to the associated header specifications. Cache Control ^^^^^^^^^^^^^ :class:`CacheControlHeader <.datastructures.headers.CacheControlHeader>` represents a `Cache-Control Header `_. Here is a simple example that shows how to use it: .. literalinclude:: /examples/datastructures/headers/cache_control.py :caption: Cache Control Header :language: python In this example we have a ``cache-control`` with ``max-age`` of 1 month for the whole app, a ``max-age`` of 1 day for all routes within ``MyController``, and ``no-store`` for one specific route ``get_server_time``. Here are the cache control values that will be returned from each endpoint: * When calling ``/population`` the response will have ``cache-control`` with ``max-age=2628288`` (1 month). * When calling ``/chance_of_rain`` the response will have ``cache-control`` with ``max-age=86400`` (1 day). * When calling ``/timestamp`` the response will have ``cache-control`` with ``no-store`` which means don't store the result in any cache. ETag ^^^^ :class:`ETag <.datastructures.headers.ETag>` represents an `ETag header `_. Here are some usage examples: .. literalinclude:: /examples/datastructures/headers/etag.py :caption: Returning ETag headers :language: python .. literalinclude:: /examples/datastructures/headers/etag_parsing.py :caption: Parsing ETag headers :language: python Setting Response Cookies ------------------------- Litestar allows you to define response cookies by using the ``response_cookies`` kwarg. This kwarg is available on all layers of the app - individual route handlers, controllers, routers, and the app itself: .. literalinclude:: /examples/responses/response_cookies_1.py :language: python In the above example, the response returned by ``my_route_handler`` will have cookies set by each layer of the application. Cookies are set using the `Set-Cookie header `_ and with above resulting in: .. code-block:: text Set-Cookie: local-cookie=local value; Path=/; SameSite=lax Set-Cookie: controller-cookie=controller value; Path=/; SameSite=lax Set-Cookie: router-cookie=router value; Path=/; SameSite=lax Set-Cookie: app-cookie=app value; Path=/; SameSite=lax You can easily override cookies declared in higher levels by redeclaring a cookie with the same key in a lower level, e.g.: .. literalinclude:: /examples/responses/response_cookies_2.py :language: python Of the two declarations of ``my-cookie`` only the route handler one will be used, because its lower level: .. code-block:: text Set-Cookie: my-cookie=456; Path=/; SameSite=lax .. tip:: If all you need for your cookies are key and value, you can supply them using a :class:`Mapping[str, str] ` - like a :class:`dict` - instead: .. code-block:: python @get(response_cookies={"my-cookie": "cookie-value"}) async def handler() -> str: ... .. seealso:: * :class:`Cookie reference <.datastructures.cookie.Cookie>` Setting Cookies dynamically ++++++++++++++++++++++++++++ While the above scheme works great for static cookie values, it doesn't allow for dynamic cookies. Because cookies are fundamentally a type of response header, we can utilize the same patterns we use to setting :ref:`set headers headers `. Using Annotated Responses ^^^^^^^^^^^^^^^^^^^^^^^^^ We can simply return a response instance directly from the route handler and set the cookies list manually as you see fit, e.g.: .. literalinclude:: /examples/responses/response_cookies_3.py :language: python In the above we use the ``response_cookies`` kwarg to pass the ``key`` and ``description`` parameters for the ``Random-Cookie`` to the OpenAPI documentation, but we set the value dynamically in as part of the :ref:`annotated response ` we return. To this end we do not set a ``value`` for it and we designate it as ``documentation_only=True``. Using the After Request Hook ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ An alternative pattern would be to use an :ref:`after request handler `. We can define the handler on different layers of the application as explained in the pertinent docs. We should take care to document the cookies on the corresponding layer: .. literalinclude:: /examples/responses/response_cookies_4.py :language: python In the above we set the cookie using an ``after_request_handler`` function on the router level. Because the handler function is applied on the router, we also set the documentation for it on the router. We can use this pattern to fine-tune the OpenAPI documentation more granular by overriding cookie specification as required. For example, lets say we have a router level cookie being set and a local cookie with the same key but a different value range: .. literalinclude:: /examples/responses/response_cookies_5.py :language: python Redirect Responses ------------------ Redirect responses are `special HTTP responses `_ with a status code in the 30x range. In Litestar, a redirect response looks like this: .. code-block:: python from litestar.status_codes import HTTP_302_FOUND from litestar import get from litestar.response import Redirect @get(path="/some-path", status_code=HTTP_302_FOUND) def redirect() -> Redirect: # do some stuff here # ... # finally return redirect return Redirect(path="/other-path") To return a redirect response you should do the following: - optionally: set an appropriate status code for the route handler (301, 302, 303, 307, 308). If not set the default of 302 will be used. - annotate the return value of the route handler as returning :class:`Redirect <.response.Redirect>` - return an instance of the :class:`Redirect <.response.Redirect>` class with the desired redirect path File Responses -------------- File responses send a file: .. code-block:: python from pathlib import Path from litestar import get from litestar.response import File @get(path="/file-download") def handle_file_download() -> File: return File( path=Path(Path(__file__).resolve().parent, "report").with_suffix(".pdf"), filename="report.pdf", ) Where ``path`` is the path of the file to be sent and ``filename`` an optional filename to set in the response `Content-Disposition `_ attachment. Media types +++++++++++ If ``filename`` is provided, Litestar will try to guess the MIME type, otherwise fall back to ``application/octet-stream``. If the type cannot be inferred via the file name, you can set it manually via ``media_type`` For example: .. code-block:: python from pathlib import Path from litestar import get from litestar.response import File @get(path="/file-download", media_type="application/pdf") def handle_file_download() -> File: return File( path=Path(Path(__file__).resolve().parent, "report").with_suffix(".pdf"), filename="report.pdf", ) Streaming +++++++++ File responses are streamed or sent in one chunk. This depends on the file's size and the ``chunk_size`` set, which defaults to 1 MB. If the file exceeds ``chunk_size``, it will be streamed. File systems ++++++++++++ :class:`~litestar.response.File` supports Litestar's *file system protocol and registry*. If no file system is passed explicitly, files will be sent using the registry's default file system, which itself defaults to :class:`~litestar.file_system.BaseLocalFileSystem`\ , sending files from disk. In addition to Litestar's own file system protocol, all `fsspec `_ file systems are supported. .. literalinclude:: /examples/responses/file_response_fs.py :language: python :caption: Sending files from S3 .. literalinclude:: /examples/responses/file_response_fs_registry.py :language: python :caption: Sending files from S3 by using the registry Streaming Responses ------------------- To return a streaming response use the :class:`Stream <.response.Stream>` class. The class receives a single positional arg, that must be an iterator delivering the stream: .. literalinclude:: /examples/responses/streaming_responses.py :language: python .. note:: You can use different kinds of values for the iterator. It can be a callable returning a sync or async generator, a generator itself, a sync or async iterator class, or an instance of a sync or async iterator class. Server Sent Event Responses --------------------------- To send `server-sent-events` or SSEs to the frontend, use the :class:`ServerSentEvent <.response.ServerSentEvent>` class. The class receives a content arg. You can additionally specify ``event_type``, which is the name of the event as declared in the browser, the ``event_id``, which sets the event source property, ``comment_message``, which is used in for sending pings, and ``retry_duration``, which dictates the duration for retrying. .. literalinclude:: /examples/responses/sse_responses.py :language: python .. note:: You can use different kinds of values for the iterator. It can be a callable returning a sync or async generator, a generator itself, a sync or async iterator class, or an instance of a sync or async iterator class. In your iterator function you can yield integers, strings or bytes, the message sent in that case will have ``message`` as the ``event_type`` if the ServerSentEvent has no ``event_type`` set, otherwise it will use the ``event_type`` specified, and the data will be the yielded value. If you want to send a different event type, you can use a dictionary with the keys ``event_type`` and ``data`` or the :class:`ServerSentEventMessage <.response.ServerSentEventMessage>` class. .. note:: You can further customize all the sse parameters, add comments, and set the retry duration by using the :class:`ServerSentEvent <.response.ServerSentEvent>` class directly or by using the :class:`ServerSentEventMessage <.response.ServerSentEventMessage>` or dictionaries with the appropriate keys. To prevent reverse proxies or clients from closing idle SSE connections, use the ``ping_interval`` parameter: .. code-block:: python @get("/stream") async def stream_handler() -> ServerSentEvent: async def generator(): while True: data = await get_data() yield data return ServerSentEvent(generator(), ping_interval=15) The ``ping_interval`` value is in **seconds**. This sends an SSE comment (``: ping``) every 15 seconds to keep the connection alive. SSE comments are invisible to ``EventSource`` clients and will not trigger message events. Pings begin after the first interval elapses (no immediate ping on connect). .. tip:: Common values are 15–30 seconds, depending on your reverse proxy's idle timeout (e.g., nginx defaults to 60 seconds, Telegram Mini Apps time out after 60 seconds). Template Responses ------------------ Template responses are used to render templates into HTML. To use a template response you must first :ref:`register a template engine ` on the application level. Once an engine is in place, you can use a template response like so: .. code-block:: python from litestar import Request, get from litestar.response import Template @get(path="/info") def info(request: Request) -> Template: return Template(template_name="info.html", context={"user": request.user}) In the above example, :class:`Template <.response.Template>` is passed the template name, which is a path like value, and a context dictionary that maps string keys into values that will be rendered in the template. Custom Responses ---------------- While Litestar supports the serialization of many types by default, sometimes you want to return something that's not supported. In those cases it's convenient to make use of a custom response class. The example below illustrates how to deal with :class:`MultiDict <.datastructures.MultiDict>` instances. .. literalinclude:: /examples/responses/custom_responses.py :language: python .. admonition:: Layered architecture :class: seealso Response classes are part of Litestar's layered architecture, which means you can set a response class on every layer of the application. If you have set a response class on multiple layers, the layer closest to the route handler will take precedence. You can read more about this here: :ref:`usage/applications:layered architecture` Background Tasks ---------------- All Litestar responses allow passing in a ``background`` kwarg. This kwarg accepts either an instance of :class:`BackgroundTask <.background_tasks.BackgroundTask>` or an instance of :class:`BackgroundTasks <.background_tasks.BackgroundTasks>`, which wraps an iterable of :class:`BackgroundTask <.background_tasks.BackgroundTask>` instances. A background task is a sync or async callable (function, method, or class that implements the :meth:`object.__call__` dunder method) that will be called after the response finishes sending the data. Thus, in the following example the passed in background task will be executed after the response sends: .. literalinclude:: /examples/responses/background_tasks_1.py :caption: Background Task Passed into Response :language: python When the ``greeter`` handler is called, the logging task will be called with any ``*args`` and ``**kwargs`` passed into the :class:`BackgroundTask <.background_tasks.BackgroundTask>`. .. note:: In the above example ``"greeter"`` is an arg and ``message=f"was called with name {name}"`` is a kwarg. The function signature of ``logging_task`` allows for this, so this should pose no problem. :class:`BackgroundTask <.background_tasks.BackgroundTask>` is typed with :class:`ParamSpec `, enabling correct type checking for arguments and keyword arguments passed to it. Route decorators (e.g. ``@get``, ``@post``, etc.) also allow passing in a background task with the ``background`` kwarg: .. literalinclude:: /examples/responses/background_tasks_2.py :caption: Background Task Passed into Decorator :language: python .. note:: Route handler arguments cannot be passed into background tasks when they are passed into decorators. Executing Multiple Background Tasks +++++++++++++++++++++++++++++++++++ You can also use the :class:`BackgroundTasks <.background_tasks.BackgroundTasks>` class and pass to it an iterable (:class:`list`, :class:`tuple`, etc.) of :class:`BackgroundTask <.background_tasks.BackgroundTask>` instances: .. literalinclude:: /examples/responses/background_tasks_3.py :caption: Multiple Background Tasks :language: python :class:`BackgroundTasks <.background_tasks.BackgroundTasks>` class accepts an optional keyword argument ``run_in_task_group`` with a default value of ``False``. Setting this to ``True`` allows background tasks to run concurrently, using an `anyio.task_group `_. .. note:: Setting ``run_in_task_group`` to ``True`` will not preserve execution order. Pagination ----------- When you need to return a large number of items from an endpoint it is common practice to use pagination to ensure clients can request a specific subset or "page" from the total dataset. Litestar supports three types of pagination out of the box: * classic pagination * limit / offset pagination * cursor pagination Classic Pagination ++++++++++++++++++ In classic pagination the dataset is divided into pages of a specific size and the consumer then requests a specific page. .. literalinclude:: /examples/pagination/using_classic_pagination.py :caption: Classic Pagination :language: python The data container for this pagination is called :class:`ClassicPagination <.pagination.ClassicPagination>`, which is what will be returned by the paginator in the above example This will also generate the corresponding OpenAPI documentation. If you require async logic, you can implement the :class:`AbstractAsyncClassicPaginator <.pagination.AbstractAsyncClassicPaginator>` instead of the :class:`AbstractSyncClassicPaginator <.pagination.AbstractSyncClassicPaginator>`. Offset Pagination +++++++++++++++++ In offset pagination the consumer requests a number of items specified by ``limit`` and the ``offset`` from the beginning of the dataset. For example, given a list of 50 items, you could request ``limit=10``, ``offset=39`` to request items 40-50. .. literalinclude:: /examples/pagination/using_offset_pagination.py :caption: Offset Pagination :language: python The data container for this pagination is called :class:`OffsetPagination <.pagination.OffsetPagination>`, which is what will be returned by the paginator in the above example This will also generate the corresponding OpenAPI documentation. If you require async logic, you can implement the :class:`AbstractAsyncOffsetPaginator <.pagination.AbstractAsyncOffsetPaginator>` instead of the :class:`AbstractSyncOffsetPaginator <.pagination.AbstractSyncOffsetPaginator>`. Offset Pagination With SQLAlchemy ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ When retrieving paginated data from the database using SQLAlchemy, the Paginator instance requires an SQLAlchemy session instance to make queries. This can be achieved with :doc:`/usage/dependency-injection` Cursor Pagination +++++++++++++++++ In cursor pagination the consumer requests a number of items specified by ``results_per_page`` and a ``cursor`` after which results are given. Cursor is unique identifier within the dataset that serves as a way to point the starting position. .. literalinclude:: /examples/pagination/using_cursor_pagination.py :caption: Cursor Pagination :language: python The data container for this pagination is called :class:`CursorPagination <.pagination.CursorPagination>`, which is what will be returned by the paginator in the above example This will also generate the corresponding OpenAPI documentation. If you require async logic, you can implement the :class:`AbstractAsyncCursorPaginator <.pagination.AbstractAsyncCursorPaginator>` instead of the :class:`AbstractSyncCursorPaginator <.pagination.AbstractSyncCursorPaginator>`.