API Reference

LucidLink Python Library

Access LucidLink filespaces from Python: streaming file I/O, fsspec integration, and LucidLink Connect.

See the Quick Start for usage examples.

class lucidlink.Client(*, storage: StorageConfig | None = None, config: ClientConfig | None = None)[source]

LucidLink SDK client.

Manages the connection to LucidLink for one service-account credential. Each Client instance is fully independent; multiple clients can run side-by-side in the same process and operate on different workspaces concurrently.

Lifecycle:

client = Client()
client.login(credentials)
workspace = client.get_workspace(workspace_id)
# ... use workspace ...
client.close()

Or as a context manager:

with Client() as client:
    client.login(credentials)
    workspace = client.get_workspace(workspace_id)
    # ... use workspace ...

Multi-client (concurrent multi-account):

client_a = Client(storage=StorageConfig(mode=StorageMode.SANDBOXED))
client_b = Client(storage=StorageConfig(mode=StorageMode.SANDBOXED))
client_a.login(creds_a)
client_b.login(creds_b)
# both fully independent, with separate storage

Note

When running multiple concurrent clients, give each one a distinct Storage so their per-filespace state lives under separate roots.

close() → None[source]

Tear down the client: unlink all filespaces and release resources.

Safe to call multiple times. After close(), the client must not be reused — create a new Client for further work.

get_workspace(id: str) → Workspace[source]

Return the workspace with the given id.

Parameters:

id – The workspace id (from list_workspaces()).

Returns:

The live Workspace for filespace operations.

Raises:

AuthenticationError – If the client is not logged in.
ValueError – If id does not match any accessible workspace.

property is_logged_in: bool: Whether login() has been called successfully and not yet close()-d.

list_workspaces() → List[WorkspaceInfo][source]

List workspaces this client’s credentials grant access to.

Returns:: A list of WorkspaceInfo descriptors, one per accessible workspace. Pass an id to get_workspace() to obtain an operable Workspace handle.
Raises:: AuthenticationError – If the client is not logged in.

login(credentials: ServiceAccountCredentials) → None[source]

Authenticate to LucidLink with a service account token.

The token determines which workspace this client operates on.

Parameters:

credentials – Service account credentials.

Raises:

AuthenticationError – If already logged in with different credentials, or if authentication fails.
ClientError – If the client cannot be started.

class lucidlink.ClientConfig(fs_cache_size_mb: int | None = None)[source]

Typed configuration for Client.

All fields are optional; None means “use the built-in default”.

Example:

client = Client(config=ClientConfig(
    fs_cache_size_mb=2048,
))

fs_cache_size_mb: int | None = None

1024 MB.

Type:: Per-filespace disk cache size in megabytes. Default

Deprecated

The Daemon facade and the create_daemon() factory are kept for backward compatibility; new code should use lucidlink.Client.

lucidlink.create_daemon(config: Dict[str, str] | None = None, sandboxed: bool = True, persist_files: bool = False, root_path: str | Path | None = None) → Daemon[source]

Create a Daemon with simplified storage configuration.

Deprecated since version Use: lucidlink.Client instead.

This is a convenience factory that makes it easier to configure daemon storage without needing to manually create StorageConfig objects.

Parameters:

config – Additional daemon configuration options (cache size, etc.)
sandboxed – If True (default), use temp directory that’s always cleaned up. If False, use .lucid subfolder in current directory.
persist_files – If False (default), clean up files when daemon stops. Only applies when sandboxed=False. Sandboxed mode always cleans up.
root_path – Override root path for files (only when sandboxed=False). If None, uses current working directory.

Returns:

Daemon instance with specified storage configuration

Example

# Sandboxed (default) - files in temp, always cleaned up
daemon = lucidlink.create_daemon()

# Physical with cleanup - files in .lucid/, cleaned up on exit
daemon = lucidlink.create_daemon(sandboxed=False)

# Physical with persistence - files in .lucid/, kept after exit
daemon = lucidlink.create_daemon(sandboxed=False, persist_files=True)

# Custom root path
daemon = lucidlink.create_daemon(
    sandboxed=False,
    root_path="D:/lucid_data",
)

# With custom config
daemon = lucidlink.create_daemon(
    config={"fs.cache.size": "2048"},
    sandboxed=False,
    persist_files=True,
)