filespace

A linked filespace: its file system, Connect, sync and maximum cache sizes.

Workspace.link_filespace() returns a Filespace, the way to its files (Filespace.file_system) and to LucidLink Connect (Filespace.connect). Filespace.sync() waits until changes have reached LucidLink services, and a SyncBarrier sets whether unlinking waits too. CacheConfig sets the maximum cache sizes of a link, and FilespaceInfo describes a filespace listed by Workspace.list_filespaces().

dataclass

lucidlink.CacheConfig

The maximum cache sizes of a linked filespace, for Workspace.link_filespace(cache=...).

The caches grow on demand up to these sizes. A size is in bytes, a non-negative integer no larger than 2**63 - 1. An invalid size makes Workspace.link_filespace() raise without linking the filespace.

A size left as None takes the first of:

the size given when this client, or a StorageMode.PERSISTENT client with the same root_path, linked this filespace before;
the filespace-wide maximum, if the filespace has one;
the SDK default: 5 GiB for the data cache, 1 GiB for the metadata cache.

A size given here is kept when the filespace is linked again, until the client closes for a StorageMode.EPHEMERAL client. A size taken from the filespace-wide maximum or the SDK default is not kept, so a change of the filespace-wide maximum applies from the next time the filespace is linked.

Parameters

Parameter	Description
`data_size`	The maximum size of the data cache in bytes, a multiple of 1 MiB; None for the size described above.
`metadata_size`	The maximum size of the metadata cache in bytes; None for the size described above.

data_size

Description: The maximum size of the data cache in bytes, a multiple of 1 MiB; None for the size described above.

metadata_size

Description: The maximum size of the metadata cache in bytes; None for the size described above.

CacheConfig example

from lucidlink import CacheConfig
# A data cache of up to 2 GiBfilespace = workspace.link_filespace("fs-uuid-12345", cache=CacheConfig(data_size=2 * 1024**3))

Attribute	Type	Description
`data_size`	`int \| None`	The maximum size of the data cache in bytes, or None.
`metadata_size`	`int \| None`	The maximum size of the metadata cache in bytes, or None.

data_size

Type: int | None
Description: The maximum size of the data cache in bytes, or None.

metadata_size

Type: int | None
Description: The maximum size of the metadata cache in bytes, or None.

class

lucidlink.Filespace

Filespace()

A filespace linked by this client.

Get it from workspace.link_filespace(). It gives access to the files of the filespace through file_system and to LucidLink Connect through connect. Use it as a context manager, or call unlink() when done; call sync() first when changes must be saved, because the final sync of unlink() is best-effort.

Errors common to every call, not repeated in each Raises section: after unlink(), version, connect, sync(), the cache size getters and the calls on its FileSystem, FsUtils and Connect objects raise FilespaceNotLinkedError, and the files opened through it, closed by unlink(), raise the ValueError of a closed file. A call that hits an internal error of the filespace raises FilespaceInternalError, and the SDK unlinks the filespace: changes not yet synced are lost, and later calls raise FilespaceNotLinkedError; link the filespace again to go on. Once the owning Client is closed, the calls raise ClientClosedError instead.

Filespace example

from lucidlink import FsUtils
with workspace.link_filespace("fs-uuid-12345") as filespace:    filespace.file_system.create_dir("/new-folder")    FsUtils(filespace.file_system).write_bytes("/new-folder/file.txt", b"data")    filespace.sync()  # when the changes must be saved# Unlinked when the block exits, after a best-effort final sync

property

connect: `ConnectManager`

The LucidLink Connect ConnectManager of the filespace: its data stores and external files.

An external file is a file of the filespace whose data is an S3 object or an HTTP URL.

Raises

Exception	Condition
`AccessDeniedError`	If the service account is not a filespace admin.

AccessDeniedError

Condition: If the service account is not a filespace admin.

Filespace.connect example

from lucidlink.connect import S3DataStoreConfig
store = filespace.connect.data_stores.add("my-store", S3DataStoreConfig(    access_key="AKIA...",    secret_key="...",    bucket_name="my-bucket",    region="us-east-1",))store.link("/file.csv", "path/to/file.csv")

property

file_system: `FileSystem`

The FileSystem of the filespace: its files, directories and symbolic links.

Filespace.file_system example

from lucidlink import FsUtils
filespace.file_system.read_dir("/")FsUtils(filespace.file_system).write_bytes("/hello.txt", b"world")

property

id: `str`

The filespace ID.

property

is_linked: `bool`

Whether the filespace is still linked.

False after unlink(), once the SDK has unlinked the filespace after an internal error, and once the owning Client is closed. Right after an internal error it can still be True for a moment.

property

name: `str`

The filespace name.

property

sync_barrier: `SyncBarrier`

Whether unlink() waits for the pending changes to reach LucidLink services first.

SyncBarrier.ON_UNLINK by default: unlink() and leaving the with block run a final sync, best-effort with no guarantee of success. SyncBarrier.NONE skips it. Changes are synced in the background either way; call sync() when they must be saved.

Raises

Exception	Condition
`TypeError`	If it is set to a value that is not a SyncBarrier.

TypeError

Condition: If it is set to a value that is not a SyncBarrier.

Filespace.sync_barrier example

from lucidlink import SyncBarrier
filespace.sync_barrier = SyncBarrier.NONE# ... changes ...filespace.sync()  # wait for the changes yourselffilespace.unlink()  # does not wait

property

version: `int`

The format of the filespace, as a number: for example 10 for filespace format 3.6, 12 for 3.8.

Connect needs filespace format 3.6 or newer, and HTTP-link data stores need 3.8; on 3.6, link HTTP URLs with lucidlink.connect.HttpConnect_3_6.

property

workspace: `Workspace`

The Workspace this filespace was linked through.

method

get_data_cache_size() -> `int`

Return the maximum size of the data cache of the linked filespace in bytes.

method

get_metadata_cache_size() -> `int`

Return the maximum size of the metadata cache of the linked filespace in bytes.

method

sync() -> `None`

Wait until the pending changes of the filespace have reached LucidLink services.

Changes are synced in the background on their own; sync() returns once every change made so far, Connect changes included, has reached LucidLink services. Other clients pick the changes up from there on their own, so they may still not see them at once. Call it before unlink() or leaving the with block when the changes must be saved: the final sync of unlink() is best-effort only. See "Sync changes" in the Getting started guide.

Filespace.sync example

from lucidlink import FsUtils
FsUtils(filespace.file_system).write_bytes("/test.txt", b"data")filespace.sync()

method

unlink() -> `None`

Unlink the filespace; other linked filespaces are not affected.

The files still open through file_system are closed first, which writes the data they buffered. Then, if sync_barrier is SyncBarrier.ON_UNLINK, a final sync runs: best-effort, with no guarantee of success, so call sync() first when changes must be saved. The final sync has no timeout: it returns once the pending changes have reached LucidLink services, or LucidLink services report a failure. The filespace is unlinked even when the close or the final sync fails.

Calling unlink() again does nothing, as does calling it once the owning Client is closed. After an internal error made the SDK unlink the filespace, the first unlink() raises FilespaceSyncError regardless of sync_barrier: the changes not yet synced were lost at that point.

Raises

Exception	Condition
`FilespaceSyncError`	If the final sync failed, or the SDK unlinked the filespace after an internal error (regardless of sync_barrier). The filespace is unlinked; a note names the cause. The unsynced changes stay in the local files of the client only, and are lost when a StorageMode.EPHEMERAL client closes; after an internal error they are lost in any case.
`FilespaceError`	If closing a file still open failed. The filespace is unlinked; a note names the failure, and another one the final sync failure when the final sync failed too.
`LucidLinkErrorGroup`	If the close or the final sync failed and unlinking failed too; it holds both failures. The filespace is still reported as linked: call unlink() again to finish unlinking.
`LucidLinkError`	If unlinking failed. The filespace is still reported as linked: call unlink() again to finish unlinking; with SyncBarrier.ON_UNLINK that call can raise FilespaceSyncError, as the final sync may no longer run.

FilespaceSyncError

Condition: If the final sync failed, or the SDK unlinked the filespace after an internal error (regardless of sync_barrier). The filespace is unlinked; a note names the cause. The unsynced changes stay in the local files of the client only, and are lost when a StorageMode.EPHEMERAL client closes; after an internal error they are lost in any case.

FilespaceError

Condition: If closing a file still open failed. The filespace is unlinked; a note names the failure, and another one the final sync failure when the final sync failed too.

LucidLinkErrorGroup

Condition: If the close or the final sync failed and unlinking failed too; it holds both failures. The filespace is still reported as linked: call unlink() again to finish unlinking.

LucidLinkError

Condition: If unlinking failed. The filespace is still reported as linked: call unlink() again to finish unlinking; with SyncBarrier.ON_UNLINK that call can raise FilespaceSyncError, as the final sync may no longer run.

dataclass

lucidlink.FilespaceInfo

A filespace of the workspace, as Workspace.list_filespaces() returns it.

Attribute	Type	Description
`id`	`str`	The filespace ID, as Workspace.link_filespace() takes it.
`name`	`str`	The filespace name.
`created_at`	`datetime`	When the filespace was created, timezone-aware in UTC.

id

Type: str
Description: The filespace ID, as Workspace.link_filespace() takes it.

name

Type: str
Description: The filespace name.

created_at

Type: datetime
Description: When the filespace was created, timezone-aware in UTC.

enum

lucidlink.SyncBarrier

Whether Filespace.unlink() waits for the pending changes to reach LucidLink services.

Set it with Filespace.sync_barrier. Changes are synced in the background regardless of the barrier.

Member	Value	Description
`NONE`	`'none'`	unlink() does not wait; call Filespace.sync() to wait for the changes.
`ON_UNLINK`	`'on_unlink'`	The default: unlink() and leaving the with block run a best-effort final sync first.

NONE

Value: 'none'
Description: unlink() does not wait; call Filespace.sync() to wait for the changes.

ON_UNLINK

Value: 'on_unlink'
Description: The default: unlink() and leaving the with block run a best-effort final sync first.

filespace

lucidlink.CacheConfig

Parameters

lucidlink.Filespace

connect: ConnectManager

Raises

file_system: FileSystem

id: str

is_linked: bool

name: str

sync_barrier: SyncBarrier

Raises

version: int

workspace: Workspace

get_data_cache_size() -> int

get_metadata_cache_size() -> int

sync() -> None

unlink() -> None

Raises

lucidlink.FilespaceInfo

lucidlink.SyncBarrier

connect: `ConnectManager`

file_system: `FileSystem`

id: `str`

is_linked: `bool`

name: `str`

sync_barrier: `SyncBarrier`

version: `int`

workspace: `Workspace`

get_data_cache_size() -> `int`

get_metadata_cache_size() -> `int`

sync() -> `None`

unlink() -> `None`