labthings_fastapi.dependencies.invocation

FastAPI dependencies for invocation-specific resources.

There are a number of LabThings-FastAPI features that are specific to each invocation of an action. These may be accessed using the Dependencies in this module.

It’s important to understand how FastAPI handles dependencies when looking at the code in this module. Each dependency (i.e. each callable passed as the argument to fastapi.Depends in an annotated type) will be evaluated only once per HTTP request. This means that we don’t need to cache InvocationID and pass it between the functions, because the same ID will be passed to every dependency that has an argument with the annotated type InvocationID.

When an action is invoked with a POST request, the endpoint function responsible always has dependencies for the InvocationID and CancelHook. These are added to the Invocation thread that is created. If the action declares dependencies with these types, it will receive the same objects. This avoids the need for the action to be aware of its Invocation.

Note

Currently, invocation_logger is called from Invocation.run with the invocation ID as an argument, and is not a direct dependency of the action’s POST endpoint.

This doesn’t duplicate the returned logger object, as logging.getLogger may be called multiple times and will return the same logging.Logger object provided it is called with the same name.

Attributes

NonWarningInvocationID

A FastAPI dependency that supplies the invocation ID.

Functions

invocation_id_internal(→ uuid.UUID)	Generate a UUID for an action invocation.
invocation_id(→ uuid.UUID)	Wrap the invocation ID dependency.
invocation_logger(→ logging.Logger)	Make a logger object for an action invocation.
invocation_cancel_hook(→ CancelHook)	Make a cancel hook for a particular invocation.

Module Contents

labthings_fastapi.dependencies.invocation.invocation_id_internal() → uuid.UUID

Generate a UUID for an action invocation.

This is for use as a FastAPI dependency (see Dependencies).

Because fastapi only evaluates each dependency once per HTTP request, the UUID we generate here is available to all of the dependencies declared by the POST endpoint that starts an action.

Any dependency that has a parameter with the type hint InvocationID will be supplied with the ID we generate here, it will be consistent within one HTTP request, and will be unique for each request (i.e. for each invocation of the action).

This dependency is used by the InvocationLogger, CancelHook and other resources to ensure they all have the same ID, even before the Invocation object has been created.

Returns:

A unique ID for the current HTTP request, i.e. for this invocation of an action.

labthings_fastapi.dependencies.invocation.NonWarningInvocationID

A FastAPI dependency that supplies the invocation ID.

This is equivalent to InvocationID, but does not raise a deprecation warning. It should only be used by internal LabThings functions.

labthings_fastapi.dependencies.invocation.invocation_id(id: NonWarningInvocationID) → uuid.UUID

Wrap the invocation ID dependency.

This exists to provide a deprecation warning, and calls invocation_id.

Parameters:

id – The invocation ID, supplied by FastAPI.

Returns:

The same invocation ID.

labthings_fastapi.dependencies.invocation.invocation_logger(id: NonWarningInvocationID) → logging.Logger

Make a logger object for an action invocation.

This function should be used as a dependency for an action, and will supply a logger that’s specific to each invocation of that action. This is how Invocation.log is generated.

Parameters:

id – The Invocation ID, supplied as a FastAPI dependency.

Returns:

A logging.Logger object specific to this invocation.

labthings_fastapi.dependencies.invocation.invocation_cancel_hook(id: NonWarningInvocationID) → CancelHook

Make a cancel hook for a particular invocation.

This is for use as a FastAPI dependency, and will create a CancelEvent for use with a particular Invocation.

Parameters:

id – The invocation ID, supplied by FastAPI.

Returns:

a CancelHook event.