gufo.blob.aio

Async backends.

Available out-of-the-box:

• MemoryBlob: Stores data in the process' memory
• FileBlob: Host filesystem.

BlobBase

Bases: ABC

Gufo Blob: async key-value object store abstraction.

This module defines a minimal interface for working with binary objects stored in a backend-agnostic keyspace.

The model is intentionally simple:

key (str) -> value (bytes)

It supports multiple backends via a URL-based loader mechanism.

This is not a filesystem abstraction: there are no directories, inodes, or POSIX semantics.

Only a flat keyspace with optional prefix scanning.

__aenter__() async

Async context manager enter.

__aexit__(exc_type, exc_val, exc_tb) async

Asynchronous context manager exit.

close() async

Perform cleanup routines when necessary.

delete(key) abstractmethod async

Delete key.

Parameters:

Name	Type	Description	Default
key	str	Object key.	required

Raises:

Type	Description
KeyError	If the key does not exist.
BlobError	On backend or I/O failure.

exists(key) abstractmethod async

Check whether a key exists in the blob store.

Parameters:

Name	Type	Description	Default
key	str	Object key.	required

Returns:

Type	Description
bool	True if the key exists, False otherwise.

Raises:

Type	Description
BlobError	On backend or I/O failure.

from_url(url) classmethod

Create a blob backend instance from a URL.

The URL defines the storage backend and its configuration. The schema part selects the backend implementation.

Examples:

/var/data memory:// s3://bucket/prefix

Parameters:

Name	Type	Description	Default
url	str	Backend-specific URL.	required

Returns:

Type	Description
BlobBase	Initialized BlobBase instance.

Raises:

Type	Description
BlobError	If the schema is unsupported or initialization fails.

get(key) abstractmethod async

Retrieve data by key.

Parameters:

Name	Type	Description	Default
key	str	Object key.	required

Raises:

Type	Description
BlobError	On backend or I/O failure.

open() async

Perform connection routines when necessary.

parse_url(url) abstractmethod classmethod

Parse URL and extract parameters for constructor.

Parameters:

Name	Type	Description	Default
url	str	URL to parse.	required

Returns:

Type	Description
dict[str, Any]	**kwargs for constructor.

put(key, data) abstractmethod async

Store binary data under the given key.

If the key already exists, its value is overwritten.

Parameters:

Name	Type	Description	Default
key	str	Object key.	required
data	bytes	Binary payload.	required

Raises:

Type	Description
BlobError	On backend or I/O failure.

scan(prefix) abstractmethod

Iterate all keys within prefix.

Parameters:

Name	Type	Description	Default
prefix	str	Prefix to scan.	required

Returns:

Type	Description
AsyncIterator[str]	Yields matched keys.

Raises:

Type	Description
BlobError	On backend or I/O failure.

BlobError

Bases: Exception

Basic Gufo Blob error class.

open_blob(url)

Open a blob store instance from URL.

This is the main entry point for creating a blob backend based on a URL schema.

The schema part of the URL selects the backend implementation, while the rest of the URL is backend-specific configuration.

Examples:

/var/data memory:/// s3://bucket/prefix

Parameters:

Name	Type	Description	Default
url	str	Storage backend URL.	required

Returns:

Type	Description
BlobBase	Initialized blob store instance.

Raises:

Type	Description
BlobError	If the schema is not supported or backend initialization fails.