workspace

Workspace context after successful authentication.

class lucidlink.workspace.Workspace(workspace_id: str, workspace_name: str)[source]

Bases: object

Workspace context after successful authentication.

Provides access to filespace operations within the authenticated workspace. Returned by Daemon.authenticate().

Multiple filespaces can be linked concurrently — each link_filespace() call returns an independent Filespace that stays usable until it is unlinked.

Example

credentials = ServiceAccountCredentials(token)
client.login(credentials)
workspace = client.get_workspace(client.list_workspaces()[0].id)
print(workspace.id, workspace.name)
property id: str

Get the workspace ID.

Link to a filespace in this workspace.

You must provide either name OR id, but not both.

Multiple filespaces can be linked at the same time: linking a second filespace does NOT unlink the first one. Each linked filespace runs a full client stack — expect roughly one disk cache (fs.cache.size, default 1024 MB) plus a set of worker threads per link.

Linking a filespace that is already linked is idempotent and returns the existing live Filespace object.

Parameters:

  • name –

    Filespace name.

    Deprecated since version Pass: id instead — a filespace name is mutable while its id is stable, so a script that worked yesterday silently links to nothing (or the wrong filespace) after a rename.

  • id – Filespace ID (recommended). Stable for the lifetime of the filespace.

  • root_path – Mount point path (default: "/")

  • sync_mode – Controls automatic sync on close. SYNC_ALL (default) calls sync_all() before unlinking. SYNC_NONE skips automatic sync — caller must call sync_all() explicitly.

Returns:

Filespace object for filesystem operations

Raises:

  • ValueError – If neither name nor id provided, or both provided

  • FileNotFoundError – If filespace not found

  • PermissionDeniedError – If service account lacks access

  • RuntimeError – If the client is not running or not authenticated

Example

# Link by ID (recommended — stable across renames)
fs = workspace.link_filespace(id="fs-uuid-12345")

# Link a second filespace — both stay usable concurrently
fs2 = workspace.link_filespace(id="fs-uuid-67890")

# Using as context manager (auto sync + unlink on exit)
with workspace.link_filespace(id="fs-uuid-12345") as fs:
    fs.fs.write_file("/file.txt", b"data")
# sync_all() + unlink() called automatically

# Disable auto-sync
fs = workspace.link_filespace(
    id="fs-uuid-12345", sync_mode=SyncMode.SYNC_NONE)

# Deprecated: link by name (emits DeprecationWarning)
fs = workspace.link_filespace(name="production-data")
property linked_filespaces: List[Filespace]

Get the currently linked Filespace objects.

list_filespaces() → List[FilespaceInfo][source]

List all filespaces in this workspace.

Returns:

List of FilespaceInfo objects with id, name, and created timestamp.

Raises:

  • ConnectionError – If LucidLink services are unreachable

  • AuthenticationError – If access token expired

  • RuntimeError – If the client is not running

Example

filespaces = workspace.list_filespaces()
for fs in filespaces:
    print(f"{fs.name}")
property name: str

Get the workspace name.

stop() → None[source]

Stop workspace — unlinks all linked filespaces.

If a filespace’s sync_mode is SYNC_ALL, sync_all() is called before it is unlinked. Per-filespace unlink errors are swallowed so one failing link never blocks the others. Safe to call multiple times.

Unlink the link identified by a native LinkedFilespace handle.

Forwarded from Daemon.unlink_filespace. When the handle maps to a tracked Filespace the teardown goes through it, so the link bookkeeping (the _linked_filespaces / _aliases entries) is dropped via the usual unlink callback. An untracked handle falls back to a direct native unlink so a live link is never leaked.

Users should call filespace.unlink() instead.