API Reference

space_manager.py

Manages logical storage spaces using the local filesystem. Supports hierarchical space creation, deletion, metadata tracking, and recursive discovery.

FIXME Mapping of space names to paths is not yet implemented. Create sub space fails FIXME Don’t remove spaces that have child spaces. Force option. FIXME Add a way to rename spaces. FIXME Add a way to move spaces.

class darca_space_manager.space_manager.SpaceManager

Bases: object

create_directory(space_name: str, relative_path: str) → str

create_space(name: str, label: str = '', parent_path: str = None) → bool

Create a new space. Supports nested structure like ‘space1/subdir’.

Args:

name (str): The name of the new space (must be unique). label (str): A label for filtering/categorization. parent_path (str): A path like ‘space1/subdir’, where the first part must be an existing space.

Returns:

bool: True if the space was created successfully.

delete_space(name: str) → bool

get_directory_last_modified(name: str, directory: str = None) → float

Return the ‘last modified’ timestamp of a space (directory), in seconds since the Unix epoch (UTC). The directory’s timestamp is the newest (i.e., highest mtime) among all files it contains, recursively. If no files exist, we fall back to the directory’s own mtime.

Args:

name (str): The name of the space.

Returns:

float: The highest file modification timestamp (UTC) in the space,

or the directory’s own timestamp if no files are found.

get_space(name: str) → dict | None

list_spaces(label_filter: str = None) → List[dict]

refresh_index()

remove_directory(space_name: str, relative_path: str) → bool

space_exists(name: str) → bool

exception darca_space_manager.space_manager.SpaceManagerException(message, error_code=None, metadata=None, cause=None)

Bases: DarcaException

space_file_manager.py

Provides file-level operations within managed logical spaces. Supports reading, writing, deleting, and listing files within spaces, with automatic handling of YAML/JSON content types.

class darca_space_manager.space_file_manager.SpaceFileManager

Bases: object

delete_file(space_name: str, relative_path: str) → bool

file_exists(space_name: str, relative_path: str) → bool

get_file(space_name: str, relative_path: str, load: bool = False) → str | dict

get_file_last_modified(space_name: str, relative_path: str) → float

list_files(space_name: str, recursive: bool = True) → List[str]

list_files_content(space_name: str) → List[dict]

Return a list describing each file within a space, including the file’s relative path, type (‘ascii’ or ‘binary’), and content if ascii.

The output is a list of dicts: [ { “file_name”: <relative path to file>, “file_content”: <ASCII text content or None>, “type”: “ascii” or “binary” }, … ]

Args:

space_name (str): The space to scan.

Returns:

List[dict]: A list of file info dictionaries.

Raises:

SpaceFileManagerException: If the space doesn’t exist or if any

unexpected I/O errors occur.

set_file(space_name: str, relative_path: str, content: str | dict) → bool

exception darca_space_manager.space_file_manager.SpaceFileManagerException(message, error_code=None, metadata=None, cause=None)

Bases: DarcaException

Custom exception for errors in the SpaceFileManager.

space_executor.py

Allows executing commands within a given space directory using the darca-executor. FIXME: Jail the command to the space directory.

class darca_space_manager.space_executor.SpaceExecutor(use_shell: bool = False)

Bases: object

Encapsulates the logic for running commands within a managed space using the darca-executor module.

run_in_space(space_name: str, command: List[str] | str, cwd: str | None = None, capture_output: bool = True, check: bool = True, env: dict | None = None, timeout: int | None = 30) → DarcaExecutor.CompletedProcess

Run a command within the specified space directory using DarcaExecutor.

Args:

space_name (str): Name of the managed space. command (List[str] | str): The command to execute. Must be a list if use_shell=False, or a string if use_shell=True. capture_output (bool): If True, captures stdout/stderr. check (bool): Raise an exception if the command exits with a non-zero code. env (Optional[dict]): Environment variables to pass to the subprocess. timeout (Optional[int]): Timeout in seconds. cwd (Optional[str]): An additional subdirectory path within the space. This will be appended to the space’s root path before passing to DarcaExecutor as the working directory (cwd).

Returns:

subprocess.CompletedProcess: The result of the subprocess execution.

Raises:

SpaceExecutorException: If the space is not found, or if execution fails for any reason.

exception darca_space_manager.space_executor.SpaceExecutorException(message: str, error_code: str = 'SPACE_EXECUTOR_ERROR', metadata: Dict | None = None, cause: Exception = None)

Bases: DarcaException

Custom exception for errors within the SpaceExecutor.