gufo.blob.sync

Synchronous backends.

Available out-of-the-box:

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

BlobBase

Bases: ABC

Gufo Blob: synchronous 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.

__contains__(item)

Check whether a key exists in the blob store.

Implements the in operator:

key in blob

This is a convenience wrapper over exists().

Parameters:

Name	Type	Description	Default
item	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.

__delitem__(key)

Delete a key from the blob store using dict-like syntax.

This is a convenience wrapper over delete().

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.

__enter__()

Context manager enter.

__exit__(exc_type, exc_val, exc_tb)

Context manager exit.

__getitem__(key)

Retrieve binary data by key using dict-like access.

This is a convenience wrapper over get().

Parameters:

Name	Type	Description	Default
key	str	Object key.	required

Returns:

Type	Description
bytes	Binary data associated with the key.

Raises:

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

__setitem__(key, data)

Store binary data under a key using dict-like assignment.

This is a convenience wrapper over put().

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.

close()

Perform cleanup routines when necessary.

delete(key) abstractmethod

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

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

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()

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

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
Iterable[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:/// sqlite:///var/data/blob.db

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.