labthings_fastapi.descriptors.endpoint
======================================

.. py:module:: labthings_fastapi.descriptors.endpoint

.. 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 `.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:`.fastapi_endpoint`. See the documentation for that function for
   more detail.



Attributes
----------

.. autoapisummary::

   labthings_fastapi.descriptors.endpoint.HTTPMethod


Classes
-------

.. autoapisummary::

   labthings_fastapi.descriptors.endpoint.EndpointDescriptor


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

.. py:data:: HTTPMethod

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


.. py:class:: EndpointDescriptor(func: Callable, http_method: HTTPMethod = 'get', path: Optional[str] = None, **kwargs: Mapping)

   A descriptor to allow Things to easily add other endpoints.

   Initialise an EndpointDescriptor.

   See `.fastapi_endpoint`, which is the usual way of instantiating this
   class.

   :param func: is the method (defined on a `.Thing`) wrapped by this
       descriptor.
   :param http_method: the HTTP verb we are responding to. This selects
       the FastAPI decorator: ``"get"`` corresponds to ``@app.get``.
   :param path: the URL, relative to the host `.Thing`, for the endpoint.
   :param \**kwargs: additional keyword arguments are passed to the
       FastAPI decorator, allowing you to specify responses, OpenAPI
       parameters, etc.


   .. py:attribute:: func


   .. py:attribute:: http_method
      :value: 'get'



   .. py:attribute:: _path
      :value: None



   .. py:attribute:: kwargs


   .. py:method:: __get__(obj: Literal[None], type=None) -> typing_extensions.Self
                  __get__(obj: labthings_fastapi.thing.Thing, type=None) -> Callable

      Bind the method to the host `.Thing` and return it.

      When called on a `.Thing`, this descriptor returns the wrapped
      function, with the `.Thing` bound as its first argument. This is
      the usual behaviour for Python methods.

      If `obj` is None, the descriptor is returned, so we can get
      the descriptor conveniently as an attribute of the class.

      :param obj: The `.Thing` on which the descriptor is defined, or ``None``.
      :param type: The class on which the descriptor is defined.

      :return: The wrapped function, bound to the `.Thing` (when called as
          an instance attribute), or the descriptor itself (when called as
          a class attribute).



   .. py:property:: name

      The name of the wrapped function.



   .. py:property:: path

      The path of the endpoint (relative to the Thing).



   .. py:property:: title

      A human-readable title.



   .. py:property:: description

      A description of the endpoint.



   .. py:method:: add_to_fastapi(app: fastapi.FastAPI, thing: labthings_fastapi.thing.Thing)

      Add an endpoint for this function to a FastAPI app.

      We will add an endpoint to the app, bound to a particular `.Thing`.
      The URL will be prefixed with the `.Thing` path, i.e. the specified
      URL (which defaults to the name of this descriptor) is relative to
      the host `.Thing`.

      :param app: the `fastapi.FastAPI` application we are adding to.
      :param thing: the `.Thing` we're bound to.