`labthings_fastapi.outputs.blob`

BLOB Output Module

The BlobOutput class is used when you need to return something file-like that can’t easily (or efficiently) be converted to JSON. This is useful for returning large objects like images, especially where an existing file-type is the obvious way to handle it.

To return a file from an action, you should declare its return type as a BlobOutput subclass, defining the media_type attribute.

The output from the class should be an instance of that subclass, with data supplied either as a bytes object or a file on disk. If files are used, it’s your responsibility to ensure the file is deleted after the BlobOutput object is garbage-collected. Constructing it using the class methods from_bytes or from_temporary_directory will ensure this is done for you.

Bear in mind a tempfile object only holds a file descriptor and is not safe for concurrent use: action outputs may be retrieved multiple times after the action has completed. Creating a temp folder and making a file inside it is the safest way to deal with this.

Module Contents

Classes

`BlobData`	A Protocol for a BlobOutput object
`ServerSideBlobData`	A BlobOutput protocol for server-side use, i.e. including `response()`
`BlobBytes`	A BlobOutput that holds its data in memory as a `bytes` object
`BlobFile`	A BlobOutput that holds its data in a file
`Blob`	An output from LabThings best returned as binary data, not JSON
`BlobDataManager`	A class to manage BlobData objects

Functions

`blob_type`	Create a BlobOutput subclass for a given media type
`blob_serialisation_context_manager`	Set context variables to allow blobs to be serialised

Data

`blobdata_to_url_ctx`
`url_to_blobdata_ctx`
`BlobIOContextDep`

API

class labthings_fastapi.outputs.blob.BlobData

Bases: typing_extensions.Protocol

A Protocol for a BlobOutput object

property media_type: str

property content: bytes

save(filename: str) → None

open() → io.IOBase

class labthings_fastapi.outputs.blob.ServerSideBlobData

Bases: labthings_fastapi.outputs.blob.BlobData, typing_extensions.Protocol

A BlobOutput protocol for server-side use, i.e. including response()

id: Optional[uuid.UUID]: None

response() → fastapi.responses.Response

class labthings_fastapi.outputs.blob.BlobBytes(data: bytes, media_type: str)

A BlobOutput that holds its data in memory as a bytes object

Initialization

id: Optional[uuid.UUID]: None

property content: bytes

save(filename: str) → None

open() → io.IOBase

response() → fastapi.responses.Response

class labthings_fastapi.outputs.blob.BlobFile(file_path: str, media_type: str, **kwargs)

A BlobOutput that holds its data in a file

Only the filepath is retained by default. If you are using e.g. a temporary directory, you should add the temporary directory as a property, to stop it being garbage collected.

Initialization

id: Optional[uuid.UUID]: None

property content: bytes

save(filename: str) → None

open() → io.IOBase

response() → fastapi.responses.Response

class labthings_fastapi.outputs.blob.Blob

Bases: pydantic.BaseModel

An output from LabThings best returned as binary data, not JSON

This may be instantiated either using the class methods from_bytes or from_temporary_directory, which will use a bytes object to store the output, or return a file on disk in a temporary directory. In the latter case, the temporary directory will be deleted when the object is garbage collected.

href: str: None

media_type: str: ‘/’

rel: Literal[output]: ‘output’

description: str: ‘The output from this action is not serialised to JSON, so it must be retrieved as a file. This link …’

_data: Optional[labthings_fastapi.outputs.blob.ServerSideBlobData]: None

retrieve_data()

to_dict() → Mapping[str, str]

classmethod default_media_type() → str

property data: labthings_fastapi.outputs.blob.ServerSideBlobData

property content: bytes

Return the the output as a bytes object

This property may return the bytes object, or if we have a file it will read the file and return the contents. Client objects may use this property to download the output.

This property is read-only. You should also only read it once, as no guarantees are given about cacheing - reading it many times risks reading the file from disk many times, or re-downloading an artifact.

save(filepath: str) → None

Save the output to a file.

This may remove the need to hold the output in memory.

open() → io.IOBase: Open the output as a binary file-like object.

classmethod from_bytes(data: bytes) → typing_extensions.Self: Create a BlobOutput from a bytes object

classmethod from_temporary_directory(folder: tempfile.TemporaryDirectory, file: str) → typing_extensions.Self

Create a BlobOutput from a file in a temporary directory

The TemporaryDirectory object will persist as long as this BlobOutput does, which will prevent it from being cleaned up until the object is garbage collected.

classmethod from_file(file: str) → typing_extensions.Self

Create a BlobOutput from a regular file

The file should exist for at least as long as the BlobOutput does; this is assumed to be the case and nothing is done to ensure it’s not temporary. If you are using temporary files, consider creating your Blob with from_temporary_directory instead.

response(): “Return a suitable response for serving the output

labthings_fastapi.outputs.blob.blob_type(media_type: str) → type[labthings_fastapi.outputs.blob.Blob]: Create a BlobOutput subclass for a given media type

class labthings_fastapi.outputs.blob.BlobDataManager

A class to manage BlobData objects

The BlobManager is responsible for serving Blob objects to clients. It holds weak references: it will not retain Blobs that are no longer in use. Most Blobs will be retained

Initialization

_blobs: weakref.WeakValueDictionary[uuid.UUID, labthings_fastapi.outputs.blob.ServerSideBlobData]: None

add_blob(blob: labthings_fastapi.outputs.blob.ServerSideBlobData) → uuid.UUID: Add a BlobOutput to the manager

get_blob(blob_id: uuid.UUID) → labthings_fastapi.outputs.blob.ServerSideBlobData: Retrieve a BlobOutput from the manager

download_blob(blob_id: uuid.UUID): Download a BlobOutput

attach_to_app(app: fastapi.FastAPI): Attach the BlobDataManager to a FastAPI app

labthings_fastapi.outputs.blob.blobdata_to_url_ctx: ‘(…)’

labthings_fastapi.outputs.blob.url_to_blobdata_ctx: ‘(…)’

async labthings_fastapi.outputs.blob.blob_serialisation_context_manager(request: fastapi.Request): Set context variables to allow blobs to be serialised

labthings_fastapi.outputs.blob.BlobIOContextDep: typing_extensions.TypeAlias: None

labthings_fastapi.outputs.blob

Module Contents

Classes

Functions

Data

API

`labthings_fastapi.outputs.blob`