storage

Storage configuration for LucidLink Python daemon.

This module provides two operational modes for managing daemon files: - SANDBOXED: Files in temporary directory, always cleaned up on exit - PHYSICAL: Files in .lucid subfolder, optional persistence

IMPORTANT: Directory Structure

The native C++ daemon automatically manages the directory structure: 1. Python passes the BASE directory to the daemon (e.g., C:/work/script/) 2. Daemon automatically adds the .lucid subdirectory 3. Daemon creates per-filespace UUID subdirectories for isolation

Example with PHYSICAL mode running from C:/work/script/:

1. StorageConfig.get_root_path() returns: C:/work/script/
2. Python passes to daemon: "C:/work/script" (forward slashes)
3. Native daemon creates directory structure:
   - C:/work/script/.lucid/{filespace1-uuid}/node.cfg
   - C:/work/script/.lucid/{filespace1-uuid}/metadb/
   - C:/work/script/.lucid/{filespace1-uuid}/cache/
4. If you link to a second filespace in the same script:
   - C:/work/script/.lucid/{filespace2-uuid}/node.cfg
   - C:/work/script/.lucid/{filespace2-uuid}/metadb/
   - C:/work/script/.lucid/{filespace2-uuid}/cache/

This prevents file clashes when multiple daemon instances link to different filespaces from the same script.

Note: Python passes paths to the daemon using forward slashes (generic format) for cross-platform compatibility, matching the behavior of Android/iOS which use boost::filesystem::generic_string().

class lucidlink.storage.StorageConfig(mode: StorageMode = StorageMode.SANDBOXED, persist_on_exit: bool = False, root_path: Path | None = None)

Bases: object

Configuration for daemon storage mode and file locations.

Parameters:

• mode – Storage mode (PHYSICAL or SANDBOXED)

• persist_on_exit – If False, clean up files when daemon stops. Only applies to PHYSICAL mode; SANDBOXED always cleans up.

• root_path – Override root path for files (only for PHYSICAL mode). If None, uses current working directory.

Example

# Sandboxed mode (default) - temp directory, always cleaned up
config = StorageConfig()

# Physical mode with cleanup
config = StorageConfig(mode=StorageMode.PHYSICAL)

# Physical mode with persistence
config = StorageConfig(
    mode=StorageMode.PHYSICAL,
    persist_on_exit=True
)

# Custom root path
config = StorageConfig(
    mode=StorageMode.PHYSICAL,
    root_path=Path("D:/lucid_data")
)

get_root_path() → Path

Get the root path for daemon files.

Returns:

Path to .lucid directory where daemon will create per-filespace UUID subdirectories for isolation.

should_cleanup() → bool

Check if files should be cleaned up on daemon stop.

Returns:

True if files should be cleaned up

class lucidlink.storage.StorageMode(*values)

Bases: Enum

Storage mode for daemon operational files.

PHYSICAL = 'physical'

Files in .lucid subfolder of script directory.

SANDBOXED = 'sandboxed'

Files in temp directory, always cleaned up.