calute.session.workspace

calute.session.workspace#

Workspace identity and management.

Provides WorkspaceIdentity for describing a workspace and WorkspaceManager for CRUD operations on workspaces.

class calute.session.workspace.WorkspaceIdentity(workspace_id: str, name: str, root_path: str | None = None, created_at: str = '', metadata: dict[str, typing.Any] = <factory>)[source]#

Bases: object

Describes a workspace and its associated metadata.

A workspace groups related sessions together under a shared identity, optionally tied to a filesystem path.

workspace_id#

Unique identifier for the workspace.

Type

str

name#

Human-readable workspace name.

Type

str

root_path#

Optional filesystem path associated with the workspace.

Type

str | None

created_at#

ISO 8601 timestamp of workspace creation.

Type

str

metadata#

Arbitrary metadata for extensibility.

Type

dict[str, Any]

Example

>>> ws = WorkspaceIdentity(workspace_id="ws-1", name="My Project")
>>> ws.name
'My Project'
created_at: str = ''#
classmethod from_dict(data: dict[str, Any]) → WorkspaceIdentity[source]#

Deserialize a WorkspaceIdentity from a plain dictionary.

Reconstructs a WorkspaceIdentity instance from a dictionary previously produced by to_dict() or any compatible mapping. Missing optional keys fall back to sensible defaults.

Parameters

data – A dictionary containing workspace identity fields. Must include workspace_id and name at minimum.

Returns

A new WorkspaceIdentity instance populated from data.

Raises

KeyError – If required keys (workspace_id, name) are missing.

Example

>>> data = {"workspace_id": "ws-1", "name": "demo"}
>>> ws = WorkspaceIdentity.from_dict(data)
>>> ws.workspace_id
'ws-1'
metadata: dict[str, Any]#
name: str#
root_path: str | None = None#
to_dict() → dict[str, Any][source]#

Serialize the workspace identity to a JSON-compatible dictionary.

Mutable containers (e.g., metadata) are shallow-copied to prevent unintended mutation of the original instance.

Returns

A dictionary containing all workspace identity fields with JSON-serializable values.

Example

>>> ws = WorkspaceIdentity(workspace_id="ws-1", name="demo")
>>> ws.to_dict()["name"]
'demo'
workspace_id: str#
class calute.session.workspace.WorkspaceManager[source]#

Bases: object

In-memory workspace manager for CRUD operations.

Provides thread-safe creation, retrieval, and listing of workspaces. Workspaces are stored in a dictionary keyed by workspace_id and protected by a threading.Lock.

_workspaces#

Internal dictionary mapping workspace IDs to identities.

_lock#

Threading lock for safe concurrent access.

Example

>>> manager = WorkspaceManager()
>>> ws = manager.create_workspace(name="test")
>>> manager.get_workspace(ws.workspace_id) is ws
True
create_workspace(name: str, root_path: str | None = None, *, workspace_id: str | None = None, metadata: dict[str, Any] | None = None) → WorkspaceIdentity[source]#

Create and register a new workspace.

Parameters

  • name – Human-readable workspace name.

  • root_path – Optional filesystem path.

  • workspace_id – Explicit ID; auto-generated if omitted.

  • metadata – Optional metadata dict.

Returns

The newly created WorkspaceIdentity.

get_workspace(workspace_id: str) → calute.session.workspace.WorkspaceIdentity | None[source]#

Retrieve a workspace by ID.

Parameters

workspace_id – The workspace ID to look up.

Returns

The WorkspaceIdentity, or None if not found.

list_workspaces() → list[calute.session.workspace.WorkspaceIdentity][source]#

List all registered workspaces.

Returns

List of WorkspaceIdentity objects.

Contents