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, sync_mode: SyncMode = SyncMode.SYNC_ALL)[source]

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.

property id: str: Get the filespace ID.

property name: str: Get the short filespace name (first segment before dot).

sync_all() → None[source]

Synchronize all pending changes to the hub.

Flushes all pending metadata and data changes to ensure they are propagated to LucidHub 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[source]

Unlink from this filespace.

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

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.

Raises:: RuntimeError – If unlink fails

property workspace_id: str: Get the workspace ID.

property workspace_name: str: Get the workspace name.