filespace

Filespace context after successful link.

Provides access to filesystem operations and external file management on a linked LucidLink filespace.

class lucidlink.filespace.Filespace(workspace_id: str, workspace_name: str, id: str, full_name: str, None], sync_mode: ~lucidlink.filespace_models.SyncMode = SyncMode.SYNC_ALL)

Bases: object

Filespace context after successful link.

Provides identity, filesystem access via the fs property, and external file operations via the connect property.

Example

# Context manager for automatic sync and unlink on exit
with workspace.link_filespace(name="data") as fs:
    fs.fs.write_file("/file.txt", b"data")
# sync_all() + unlink() called automatically

# Manual lifecycle
filespace = workspace.link_filespace(name="production-data")
entries = filespace.fs.read_dir("/")
filespace.fs.create_dir("/new-folder")
with filespace.fs.open("/file.txt", "wb") as f:
    f.write(b"data")

property connect: ConnectManager

Get the ConnectManager interface for external file operations.

Provides access to data store management and external file linking. External files are read-only S3 objects mapped 1:1 as files in the filespace.

Returns:

ConnectManager for data store and external file operations

Raises:

RuntimeError – If Connect is not available (e.g., filespace version too old)

Example

connect = filespace.connect
connect.add_data_store("my-store", S3DataStoreConfig(...))
connect.link_file("/data/file.csv", "my-store", "path/to/file.csv")

property fs: Filesystem

Get the Filesystem interface for file and directory operations.

Returns:

Filesystem object providing read_dir, write_file, open, and all other filesystem operations.

Example

filespace.fs.read_dir("/")
filespace.fs.write_file("/hello.txt", b"world")

property full_name: str

Get the full filespace name.

get_data_cache_size() → int

Return this filespace’s currently configured data cache size in bytes.

Raises:

RuntimeError – If the filespace is no longer linked.

get_metadata_cache_size() → int

Return this filespace’s currently configured metadata cache size in bytes.

Raises:

RuntimeError – If the filespace is no longer linked.

property id: str

Get the filespace ID.

property is_linked: bool

Whether this filespace is still linked (unlink() not yet called).

Also flips to False when the daemon reports the link torn down after a filespace internal error; until that notification is dispatched it may report a stale True.

property name: str

Get the short filespace name (first segment before dot).

sync_all() → None

Synchronize all pending changes to LucidLink services.

Flushes all pending metadata and data changes to ensure they are propagated to LucidLink services and become visible to other clients.

Covers all subsystems — filesystem operations, Connect/external file changes, and any other pending metadata updates.

Call this method after write operations (create, modify, delete) to guarantee changes are committed before reading them back or expecting them to be visible to other clients.

Example

filespace.fs.write_file("/test.txt", b"data")
filespace.sync_all()  # Ensure write is committed
# Now other clients can see the file

Raises:

RuntimeError – If sync fails

unlink() → None

Unlink from this filespace.

If sync_mode is SYNC_ALL (default), automatically calls sync_all() before unlinking to ensure pending changes are propagated to LucidLink services.

Only this link is torn down — other linked filespaces are unaffected. After calling this method, the filespace object becomes invalid and cannot be used for filesystem operations.

Safe to call multiple times — subsequent calls are no-ops. On a filespace whose link the daemon already tore down (filespace internal error) this just clears local bookkeeping; it never raises for that.

Raises:

RuntimeError – If unlink fails

property workspace_id: str

Get the workspace ID.

property workspace_name: str

Get the workspace name.