labthings_fastapi.dependencies.thing_server
===========================================

.. py:module:: labthings_fastapi.dependencies.thing_server

.. autoapi-nested-parse::

   Retrieve the `.ThingServer` object.

   This module provides a function that will retrieve the `.ThingServer`
   based on the `fastapi.Request` object. It may be used as a dependency with
   ``Annotated[ThingServer, Depends(thing_server_from_request)]``.

   See :ref:`dependencies` for more information on the dependency mechanism,
   and :ref:`things_from_things` for more on how `.Things` interact.

   .. note::

       This module does not provide a ready-made annotated type to use as a
       dependency. Doing so would mean this module has a hard dependency on
       `.ThingServer` and cause circular references. See above for the
       annotated type, which you may define in any code that needs it.

   .. note::

       The rationale for this function is that we want to make sure `.Thing`
       instances only access the server associated with the current request.
       This means that we use the `fastapi.Request` to look up the
       `fastapi.FastAPI` app, and then use the app to look up the `.ThingServer`.

       As each `.Thing` is connected to exactly one `.ThingServer`, this may
       become unnecessary in the future as the server could be exposed as a
       property of the `.Thing`.



Attributes
----------

.. autoapisummary::

   labthings_fastapi.dependencies.thing_server._thing_servers


Functions
---------

.. autoapisummary::

   labthings_fastapi.dependencies.thing_server.find_thing_server
   labthings_fastapi.dependencies.thing_server.thing_server_from_request


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

.. py:data:: _thing_servers
   :type:  weakref.WeakSet[labthings_fastapi.server.ThingServer]

.. py:function:: find_thing_server(app: fastapi.FastAPI) -> labthings_fastapi.server.ThingServer

   Find the ThingServer associated with an app.

   This function will return the `.ThingServer` object that contains
   a particular `fastapi.FastAPI` app. The app is available as part
   of the `fastapi.Request` object, so this makes it possible to
   get the `.ThingServer` in dependency functions.

   This function will not work as a dependency, but
   `.thing_server_from_request` will.

   :param app: The `fastapi.FastAPI` application that implements the
       `.ThingServer`, i.e. this is ``thing_server.app``.

   :return: the `.ThingServer` that owns the ``app``.

   :raise RuntimeError: if there is no `.ThingServer` associated
       with the current FastAPI application. This should only happen
       if this function is called on a `fastapi.FastAPI` instance
       that was not created by a `.ThingServer`.


.. py:function:: thing_server_from_request(request: fastapi.Request) -> labthings_fastapi.server.ThingServer

   Retrieve the `.ThingServer` from a request.

   This is for use as a FastAPI dependency, so the thing server is
   retrieved from the request object. See `.find_thing_server`.

   It may be used as a dependency with:

   .. code-block:: python

       ServerDep = Annotated[ThingServer, Depends(thing_server_from_request)]

   This is not provided as a ready-made annotated type because it would
   introduce a hard dependency on the :mod:`.server` module and cause circular
   references.

   :param request: is supplied automatically by FastAPI when used
       as a dependency.

   :return: the `.ThingServer` handling the current request.