labthings_fastapi.endpoints
===========================

.. py:module:: labthings_fastapi.endpoints

.. autoapi-nested-parse::

   Add a FastAPI endpoint without making it an action.

   The `.EndpointDescriptor` wraps a function and marks it to be added to the
   HTTP API at the same time as the properties and actions of the host `~lt.Thing`.
   This is intended to allow flexibility to implement endpoints that cannot be
   described in a Thing Description as actions or properties.

   It may use any `fastapi` responses or arguments, as it passes keyword
   arguments through to the relevant `fastapi` decorator.

   This will most usually be applied as a decorator with arguments, available
   as :deco:`.endpoint`. See the documentation for that function for
   more detail.



Attributes
----------

.. autoapisummary::

   labthings_fastapi.endpoints.HTTPMethod


Functions
---------

.. autoapisummary::

   labthings_fastapi.endpoints.endpoint


Module Contents
---------------

.. py:data:: HTTPMethod

   Valid HTTP verbs to use with `.endpoint` or `.EndpointDescriptor`.


.. py:function:: endpoint(method: HTTPMethod, path: Optional[str] = None, **kwargs: Any) -> Callable[[Callable], EndpointDescriptor]

   Mark a function as a FastAPI endpoint without making it an action.

   This decorator will cause a method of a `~lt.Thing` to be directly added to
   the HTTP API, bypassing the machinery underlying Action and Property
   affordances. Such endpoints will not be documented in the :ref:`wot_td` but
   may be used as the target of links. For example, this could allow a file
   to be downloaded from the `~lt.Thing` at a known URL, or serve a video stream
   that wouldn't be supported as a `.Blob`\ .

   The majority of `~lt.Thing` implementations won't need this decorator, but
   it is here to enable flexibility when it's needed.

   This decorator always takes arguments; in particular, ``method`` is
   required. It should be used as:

   .. code-block:: python

       class DownloadThing(Thing):
           @endpoint("get")
           def plain_text_response(self) -> str:
               return "example string"

   This decorator is intended to work very similarly to the `fastapi` decorators
   ``@app.get``, ``@app.post``, etc., with two changes:

   1. The path is relative to the host `~lt.Thing` and will default to the name
       of the method.
   2. The method will be called with the host `~lt.Thing` as its first argument,
       i.e. it will be bound to the class as usua.

   :param method: The HTTP verb this endpoint responds to.
   :param path: The path, relative to the host `~lt.Thing` base URL.
   :param \**kwargs: Additional keyword arguments are passed to the
       `fastapi.FastAPI.get` decorator if ``method`` is ``get``, or to
       the equivalent decorator for other HTTP verbs.

   :return: When used as intended, the result is an `.EndpointDescriptor`.