labthings_fastapi.decorators
============================

.. py:module:: labthings_fastapi.decorators

.. autoapi-nested-parse::

   Mark the Interaction Affordances of a Thing.

   See :ref:`wot_cc` for definitions of Interaction Affordance and other terms.

   LabThings generates a :ref:`wot_td` to allow actions, properties, and
   events to be used by client code. The descriptions of each "interaction
   affordance" rely on docstrings and Python type hints to provide a full
   description of the parameters, so it's important that you use these
   effectively.

   If you have a complex datatype, it's recommended to use a `pydantic` model
   to describe it - this is often the case for complicated properties or events.
   For actions, a model is created automatically based on the function's
   signature: if you want to add descriptions or validators to individual
   arguments, you may use `pydantic.Field` to do this.

   Actions
   -------

   You can add an Action to a Thing by declaring a method, decorated with
   :deco:`.thing_action`. Parameters are not usually needed, but can be supplied to set
   various options.

   Properties
   ----------

   As with Actions, Properties can be declared by decorating either a function, or
   an attribute, with :deco:`.thing_property`. You can use the decorator either on
   a function (in which case that
   function acts as the "getter" just like with Python's :deco`property` decorator).

   Events
   ------

   Events are created by decorating attributes with :deco:`.thing_event`. Functions are
   not supported at this time.



Attributes
----------

.. autoapisummary::

   labthings_fastapi.decorators.HTTPMethod


Functions
---------

.. autoapisummary::

   labthings_fastapi.decorators.return_type
   labthings_fastapi.decorators.mark_thing_action


Package Contents
----------------

.. py:data:: HTTPMethod

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


.. py:function:: return_type(func: Callable) -> Type

   Determine the return type of a function.

   :param func: a function to inspect

   :return: the return type of the function.


.. py:function:: mark_thing_action(func: Callable, **kwargs) -> labthings_fastapi.descriptors.ActionDescriptor

   Mark a method of a Thing as an Action.

   We replace the function with a descriptor that's a
   subclass of `.ActionDescriptor`

   :param func: The function to be decorated.
   :param \**kwargs: Additional keyword arguments are passed to the constructor
       of `.ActionDescriptor`.

   :return: An `.ActionDescriptor` wrapping the method.