filespace
Filespace context after successful link.
Provides access to filesystem operations and external file management on a linked LucidLink filespace.
lucidlink.filespace.Filespace
Filespace(workspace_id: str, workspace_name: str, id: str, full_name: str, sync_mode: SyncMode = SyncMode.SYNC_ALL)Parameter | Description |
|---|---|
| Workspace identifier |
| Workspace name |
| Filespace unique identifier |
| Full filespace name (may include workspace prefix) |
| Controls automatic sync on close (default: SYNC_ALL) |
workspace_id
Description
Workspace identifier
workspace_name
Description
Workspace name
id
Description
Filespace unique identifier
full_name
Description
Full filespace name (may include workspace prefix)
sync_mode
Description
Controls automatic sync on close (default: SYNC_ALL)
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 exitwith workspace.link_filespace(name="data") as fs:fs.fs.write_file("/file.txt", b"data")# sync_all() + unlink() called automatically# Manual lifecyclefilespace = 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")
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
Exception | Condition |
|---|---|
| If Connect is not available (e.g., filespace version too old) |
RuntimeError
Condition
If Connect is not available (e.g., filespace version too old)
Example
connect = filespace.connectconnect.add_data_store("my-store", S3DataStoreConfig(...))connect.link_file("/data/file.csv", "my-store", "path/to/file.csv")
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")
full_name: str
Get the full filespace name.
id: str
Get the filespace ID.
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.
name: str
Get the short filespace name (first segment before dot).
workspace_id: str
Get the workspace ID.
workspace_name: str
Get the workspace name.
get_data_cache_size() -> int
Return this filespace's currently configured data cache size in bytes.
Raises
Exception | Condition |
|---|---|
| If the filespace is no longer linked. |
RuntimeError
Condition
If the filespace is no longer linked.
get_metadata_cache_size() -> int
Return this filespace's currently configured metadata cache size in bytes.
Raises
Exception | Condition |
|---|---|
| If the filespace is no longer linked. |
RuntimeError
Condition
If the filespace is no longer linked.
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.
Raises
Exception | Condition |
|---|---|
| If sync fails |
RuntimeError
Condition
If sync fails
Example
filespace.fs.write_file("/test.txt", b"data")filespace.sync_all() # Ensure write is committed# Now other clients can see the file
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
Exception | Condition |
|---|---|
| If unlink fails |
RuntimeError
Condition
If unlink fails