filesystem

Filesystem operations on a linked LucidLink filespace.

Provides file, directory, metadata, and locking operations. Accessed via filespace.fs after linking to a filespace.

class

lucidlink.filesystem.FileHandle

FileHandle(filesystem: 'Filesystem', path: str, mode: str)

Context manager for file handles (legacy API).

Provides Pythonic file operations with automatic handle cleanup. Use with 'with' statement to ensure handles are properly closed.

Example

with fs.open_legacy("/path/to/file.txt", "r") as fh:    data = fh.read()# Handle automatically closed

property

closed: `bool`

Check if the file handle is closed.

property

mode: `str`

Get the file open mode.

property

path: `str`

Get the file path.

method

close() -> `None`

Close the file handle. Safe to call multiple times.

method

read(size: `int` = -1, offset: `int` = 0) -> `bytes`

Read data from the file.

Parameters

Parameter	Description
`size`	Number of bytes to read (-1 = read entire file)
`offset`	Byte offset to start reading from

size

Description: Number of bytes to read (-1 = read entire file)

offset

Description: Byte offset to start reading from

Returns

Bytes read from the file

method

write(data: `bytes`, offset: `int` = 0) -> `None`

Write data to the file.

Parameters

Parameter	Description
`data`	Bytes to write to the file
`offset`	Byte offset to start writing at

data

Description: Bytes to write to the file

offset

Description: Byte offset to start writing at

class

lucidlink.filesystem.Filesystem

Filesystem()

Filesystem operations on a linked LucidLink filespace.

Provides file, directory, metadata, and locking operations. Obtained via the filespace.fs property after linking.

Example

filespace = 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")

method

create(path: `str`) -> `int`

Create a new file and return a handle ID.

Use open() with mode="w" for most cases. This is a low-level API.

Parameters

Parameter	Description
`path`	File path to create

path

Description: File path to create

Returns

File handle ID (use with read/write/close methods)

Raises

Exception	Condition
`FileExistsError`	If file already exists
`PermissionError`	If no create permission

FileExistsError

Condition: If file already exists

PermissionError

Condition: If no create permission

method

create_dir(path: `str`) -> `None`

Create a directory.

Parameters

Parameter	Description
`path`	Directory path to create

path

Description: Directory path to create

Raises

Exception	Condition
`FileNotFoundError`	If the parent directory does not exist
`FileExistsError`	If directory already exists
`PermissionError`	If no create permission

FileNotFoundError

Condition: If the parent directory does not exist

FileExistsError

Condition: If directory already exists

PermissionError

Condition: If no create permission

method

create_symlink(target_path: `str`, link_path: `str`) -> `None`

Create a symbolic link.

Parameters

Parameter	Description
`target_path`	Path the symlink points to
`link_path`	Path of the symlink to create

target_path

Description: Path the symlink points to

link_path

Description: Path of the symlink to create

Raises

Exception	Condition
`FileExistsError`	If link_path already exists
`PermissionError`	If no create permission

FileExistsError

Condition: If link_path already exists

PermissionError

Condition: If no create permission

method

delete(path: `str`) -> `None`

Delete a file.

Parameters

Parameter	Description
`path`	File path to delete

path

Description: File path to delete

Raises

Exception	Condition
`FileNotFoundError`	If file doesn't exist
`IsADirectoryError`	If path is a directory
`PermissionError`	If no delete permission

FileNotFoundError

Condition: If file doesn't exist

IsADirectoryError

Condition: If path is a directory

PermissionError

Condition: If no delete permission

method

delete_dir(path: `str`, recursive: `bool` = False) -> `None`

Delete a directory.

Parameters

Parameter	Description
`path`	Directory path to delete
`recursive`	If True, delete non-empty directories (default: False)

path

Description: Directory path to delete

recursive

Description: If True, delete non-empty directories (default: False)

Raises

Exception	Condition
`FileNotFoundError`	If directory doesn't exist
`NotADirectoryError`	If path is not a directory
`OSError`	If directory is not empty and recursive=False
`PermissionError`	If no delete permission

FileNotFoundError

Condition: If directory doesn't exist

NotADirectoryError

Condition: If path is not a directory

OSError

Condition: If directory is not empty and recursive=False

PermissionError

Condition: If no delete permission

method

dir_exists(path: `str`) -> `bool`

Check if a directory exists.

Parameters

Parameter	Description
`path`	Directory path to check

path

Description: Directory path to check

Returns

True if directory exists, False otherwise

method

file_exists(path: `str`) -> `bool`

Check if a file exists.

Parameters

Parameter	Description
`path`	File path to check

path

Description: File path to check

Returns

True if file exists, False otherwise

method

get_entry(path: `str`) -> `DirEntry`

Get metadata for a file or directory.

Parameters

Parameter	Description
`path`	Path to get metadata for

path

Description: Path to get metadata for

Returns

DirEntry with entry information

Raises

Exception	Condition
`FileNotFoundError`	If path doesn't exist

FileNotFoundError

Condition: If path doesn't exist

method

get_size() -> `FilespaceSize`

Get filespace size information.

Returns

FilespaceSize with entries, data, storage, and external file info

Raises

Exception	Condition
`RuntimeError`	If operation fails

RuntimeError

Condition: If operation fails

method

get_statistics() -> `FilespaceStatistics`

Get filespace statistics.

Returns

FilespaceStatistics with file/directory counts and size info

Raises

Exception	Condition
`RuntimeError`	If operation fails

RuntimeError

Condition: If operation fails

method

list_dir(path: `str`) -> `List[str]`

List directory contents, returning just filenames (convenience method).

Parameters

Parameter	Description
`path`	Directory path to list

path

Description: Directory path to list

Returns

List of filenames (not full paths)

Raises

Exception	Condition
`NotADirectoryError`	If path is not a directory
`FileNotFoundError`	If directory doesn't exist

NotADirectoryError

Condition: If path is not a directory

FileNotFoundError

Condition: If directory doesn't exist

method

lock_byte_range(handle_id: `int`, offset: `int`, length: `int`, lock_type: `str` = 'exclusive', blocking: `bool` = True) -> `bool`

Lock a byte range of an open file.

Acquires a lock on the specified byte range. Locks are coordinated through LucidLink services, ensuring proper mutual exclusion across all clients accessing the filespace.

Parameters

Parameter	Description
`handle_id`	File handle ID from a low-level open operation
`offset`	Start offset of the byte range to lock (0 for whole file)
`length`	Length of the byte range to lock (use file size for whole file)
`lock_type`	Lock type (default: "exclusive"): - "exclusive": Exclusive lock (no other locks allowed) - "shared" or "read": Shared read lock (multiple readers allowed) - "write": Protected write lock
`blocking`	If True (default), wait until lock is available. If False, return immediately if lock unavailable.

handle_id

Description: File handle ID from a low-level open operation

offset

Description: Start offset of the byte range to lock (0 for whole file)

length

Description: Length of the byte range to lock (use file size for whole file)

lock_type

Description: Lock type (default: "exclusive"): - "exclusive": Exclusive lock (no other locks allowed) - "shared" or "read": Shared read lock (multiple readers allowed) - "write": Protected write lock

blocking

Description: If True (default), wait until lock is available. If False, return immediately if lock unavailable.

Returns

True if lock was acquired, False if non-blocking and lock unavailable

Raises

Exception	Condition
`RuntimeError`	If handle is invalid or lock operation fails
`ValueError`	If lock_type is invalid

RuntimeError

Condition: If handle is invalid or lock operation fails

ValueError

Condition: If lock_type is invalid

Example

handle_id = filespace.fs._native.open("/data.db", "r+b")try:    if filespace.fs.lock_byte_range(handle_id, 0, 1, "exclusive"):        # Perform exclusive operations        passfinally:    filespace.fs.unlock_byte_range(handle_id, 0, 1)    filespace.fs._native.close(handle_id)

method

move(src: `str`, dst: `str`) -> `None`

Move/rename a file or directory.

Parameters

Parameter	Description
`src`	Source path
`dst`	Destination path

src

Description: Source path

dst

Description: Destination path

Raises

Exception	Condition
`FileNotFoundError`	If source doesn't exist
`FileExistsError`	If destination already exists
`PermissionError`	If no move permission

FileNotFoundError

Condition: If source doesn't exist

FileExistsError

Condition: If destination already exists

PermissionError

Condition: If no move permission

method

open(path: `str`, mode: `str` = 'rb', buffering: `int` = -1, encoding: `Optional[str]` = None, errors: `Optional[str]` = None, newline: `Optional[str]` = None, lock_type: `str` = '') -> `Union[LucidFileStream, io.BufferedReader, io.BufferedWriter, io.TextIOWrapper]`

Open a file with streaming support.

Returns an io.RawIOBase-compatible stream that works with standard Python libraries and third-party packages (Pandas, LangChain, PyTorch, etc.).

Parameters

Parameter	Description
`path`	File path to open
`mode`	Open mode (default: 'rb'): - 'r': Read text (default encoding: utf-8) - 'w': Write text (create/truncate, default encoding: utf-8) - 'a': Append text (default encoding: utf-8) - 'r+': Read/write text (default encoding: utf-8) - 'w+': Write/read text (create/truncate, default encoding: utf-8) - 'rb': Read binary - 'wb': Write binary (create/truncate) - 'ab': Append binary - 'r+b': Read/write binary - 'w+b': Write/read binary (create/truncate) - 'a+b': Append/read binary - 'rt': Read text (explicit, same as 'r') - 'wt': Write text (explicit, same as 'w')
`buffering`	Buffer size: - -1 (default): Use system default (8192 bytes) - 0: Unbuffered (binary modes only) - 1: Line buffered (text mode only) - >1: Buffer size in bytes
`encoding`	Text encoding (e.g., 'utf-8', 'latin-1') Required for text modes ('r', 'w' without 'b')
`errors`	Error handling ('strict', 'ignore', 'replace')
`newline`	Newline handling (None, '', '\n', '\r', '\r\n')
`lock_type`	Lock type - "" (no lock), "shared" (read), "exclusive" (write). Lock is held for lifetime of file handle and released on close.

path

Description: File path to open

mode

Description: Open mode (default: 'rb'): - 'r': Read text (default encoding: utf-8) - 'w': Write text (create/truncate, default encoding: utf-8) - 'a': Append text (default encoding: utf-8) - 'r+': Read/write text (default encoding: utf-8) - 'w+': Write/read text (create/truncate, default encoding: utf-8) - 'rb': Read binary - 'wb': Write binary (create/truncate) - 'ab': Append binary - 'r+b': Read/write binary - 'w+b': Write/read binary (create/truncate) - 'a+b': Append/read binary - 'rt': Read text (explicit, same as 'r') - 'wt': Write text (explicit, same as 'w')

buffering

Description: Buffer size: - -1 (default): Use system default (8192 bytes) - 0: Unbuffered (binary modes only) - 1: Line buffered (text mode only) - >1: Buffer size in bytes

encoding

Description: Text encoding (e.g., 'utf-8', 'latin-1') Required for text modes ('r', 'w' without 'b')

errors

Description: Error handling ('strict', 'ignore', 'replace')

newline

Description: Newline handling (None, '', '\n', '\r', '\r\n')

lock_type

Description: Lock type - "" (no lock), "shared" (read), "exclusive" (write). Lock is held for lifetime of file handle and released on close.

Returns

File stream object supporting read, write, seek, tell operations. Compatible with context managers (with statement).

Raises

Exception	Condition
`FileNotFoundError`	If file doesn't exist (read mode)
`PermissionError`	If no access permission
`ValueError`	If mode is invalid

FileNotFoundError

Condition: If file doesn't exist (read mode)

PermissionError

Condition: If no access permission

ValueError

Condition: If mode is invalid

Example

# Binary modewith filespace.fs.open("/file.dat", "rb") as f:    data = f.read()
# Text modewith filespace.fs.open("/file.txt", "rt", encoding="utf-8") as f:    for line in f:        print(line.strip())
# With Pandaswith filespace.fs.open("/data.csv", "rb") as f:    df = pd.read_csv(f)
# Writingwith filespace.fs.open("/output.txt", "wb") as f:    f.write(b"Hello, LucidLink!")
# With exclusive locking (SQLite-style)with filespace.fs.open("/db.sqlite", "r+b", lock_type="exclusive") as f:    data = f.read()

method

open_legacy(path: `str`, mode: `str` = 'r') -> `FileHandle`

Open a file using legacy FileHandle API (deprecated).

This method is preserved for backward compatibility. New code should use open() instead, which returns a more capable io.RawIOBase stream.

Parameters

Parameter	Description
`path`	File path to open
`mode`	Open mode ('r', 'w', 'a')

path

Description: File path to open

mode

Description: Open mode ('r', 'w', 'a')

Returns

FileHandle context manager

Raises

Exception	Condition
`FileNotFoundError`	If file doesn't exist (read mode)
`PermissionError`	If no access permission

FileNotFoundError

Condition: If file doesn't exist (read mode)

PermissionError

Condition: If no access permission

method

read_dir(path: `str`) -> `List[DirEntry]`

List directory contents.

Parameters

Parameter	Description
`path`	Directory path to list

path

Description: Directory path to list

Returns

List of DirEntry objects with file entry information.

Raises

Exception	Condition
`NotADirectoryError`	If path is not a directory
`FileNotFoundError`	If directory doesn't exist
`PermissionError`	If no read permission

NotADirectoryError

Condition: If path is not a directory

FileNotFoundError

Condition: If directory doesn't exist

PermissionError

Condition: If no read permission

method

read_file(path: `str`) -> `bytes`

Read entire file contents (convenience method).

Parameters

Parameter	Description
`path`	File path to read

path

Description: File path to read

Returns

File contents as bytes

Raises

Exception	Condition
`FileNotFoundError`	If file doesn't exist
`PermissionError`	If no read permission

FileNotFoundError

Condition: If file doesn't exist

PermissionError

Condition: If no read permission

method

read_symlink(link_path: `str`) -> `str`

Read the target of a symbolic link.

Parameters

Parameter	Description
`link_path`	Path of the symlink

link_path

Description: Path of the symlink

Returns

Target path the symlink points to

Raises

Exception	Condition
`FileNotFoundError`	If link_path does not exist
`OSError`	If link_path is not a symlink

FileNotFoundError

Condition: If link_path does not exist

OSError

Condition: If link_path is not a symlink

method

truncate(path: `str`, size: `int`) -> `None`

Truncate or extend file to specified size.

Parameters

Parameter	Description
`path`	File path to truncate
`size`	New file size in bytes

path

Description: File path to truncate

size

Description: New file size in bytes

Raises

Exception	Condition
`FileNotFoundError`	If file doesn't exist
`PermissionError`	If no write permission
`RuntimeError`	If truncation fails

FileNotFoundError

Condition: If file doesn't exist

PermissionError

Condition: If no write permission

RuntimeError

Condition: If truncation fails

method

unlock_all_byte_ranges(handle_id: `int`) -> `None`

Unlock all byte ranges on an open file.

Releases all previously acquired locks on the file.

Parameters

Parameter	Description
`handle_id`	File handle ID from a low-level open operation

handle_id

Description: File handle ID from a low-level open operation

Raises

Exception	Condition
`RuntimeError`	If handle is invalid or unlock fails

RuntimeError

Condition: If handle is invalid or unlock fails

method

unlock_byte_range(handle_id: `int`, offset: `int`, length: `int`) -> `None`

Unlock a byte range of an open file.

Releases a previously acquired lock on the specified byte range.

Parameters

Parameter	Description
`handle_id`	File handle ID from a low-level open operation
`offset`	Start offset of the byte range to unlock
`length`	Length of the byte range to unlock

handle_id

Description: File handle ID from a low-level open operation

offset

Description: Start offset of the byte range to unlock

length

Description: Length of the byte range to unlock

Raises

Exception	Condition
`RuntimeError`	If handle is invalid or unlock fails

RuntimeError

Condition: If handle is invalid or unlock fails

method

write_file(path: `str`, data: `bytes`) -> `None`

Write data to file, creating it if needed (convenience method).

Parameters

Parameter	Description
`path`	File path to write
`data`	Bytes to write

path

Description: File path to write

data

Description: Bytes to write

Raises

Exception	Condition
`PermissionError`	If no permission to write file
`TypeError`	If data is not bytes

PermissionError

Condition: If no permission to write file

TypeError

Condition: If data is not bytes

filesystem

lucidlink.filesystem.FileHandle

closed: bool

mode: str

path: str

close() -> None

read(size: int = -1, offset: int = 0) -> bytes

Parameters

Returns

write(data: bytes, offset: int = 0) -> None

Parameters

lucidlink.filesystem.Filesystem

create(path: str) -> int

Parameters

Returns

Raises

create_dir(path: str) -> None

Parameters

Raises

create_symlink(target_path: str, link_path: str) -> None

Parameters

Raises

delete(path: str) -> None

Parameters

Raises

delete_dir(path: str, recursive: bool = False) -> None

Parameters

Raises

dir_exists(path: str) -> bool

Parameters

Returns

file_exists(path: str) -> bool

Parameters

Returns

get_entry(path: str) -> DirEntry

Parameters

Returns

Raises

get_size() -> FilespaceSize

Returns

Raises

get_statistics() -> FilespaceStatistics

Returns

Raises

list_dir(path: str) -> List[str]

Parameters

Returns

Raises

lock_byte_range(handle_id: int, offset: int, length: int, lock_type: str = 'exclusive', blocking: bool = True) -> bool

Parameters

Returns

Raises

move(src: str, dst: str) -> None

Parameters

Raises

open(path: str, mode: str = 'rb', buffering: int = -1, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None, lock_type: str = '') -> Union[LucidFileStream, io.BufferedReader, io.BufferedWriter, io.TextIOWrapper]

Parameters

Returns

Raises

open_legacy(path: str, mode: str = 'r') -> FileHandle

Parameters

Returns

Raises

read_dir(path: str) -> List[DirEntry]

Parameters

Returns

Raises

read_file(path: str) -> bytes

Parameters

Returns

Raises

read_symlink(link_path: str) -> str

Parameters

Returns

Raises

truncate(path: str, size: int) -> None

Parameters

Raises

unlock_all_byte_ranges(handle_id: int) -> None

Parameters

closed: `bool`

mode: `str`

path: `str`

close() -> `None`

read(size: `int` = -1, offset: `int` = 0) -> `bytes`

write(data: `bytes`, offset: `int` = 0) -> `None`

create(path: `str`) -> `int`

create_dir(path: `str`) -> `None`

create_symlink(target_path: `str`, link_path: `str`) -> `None`

delete(path: `str`) -> `None`

delete_dir(path: `str`, recursive: `bool` = False) -> `None`

dir_exists(path: `str`) -> `bool`

file_exists(path: `str`) -> `bool`

get_entry(path: `str`) -> `DirEntry`

get_size() -> `FilespaceSize`

get_statistics() -> `FilespaceStatistics`

list_dir(path: `str`) -> `List[str]`

lock_byte_range(handle_id: `int`, offset: `int`, length: `int`, lock_type: `str` = 'exclusive', blocking: `bool` = True) -> `bool`

move(src: `str`, dst: `str`) -> `None`

open(path: `str`, mode: `str` = 'rb', buffering: `int` = -1, encoding: `Optional[str]` = None, errors: `Optional[str]` = None, newline: `Optional[str]` = None, lock_type: `str` = '') -> `Union[LucidFileStream, io.BufferedReader, io.BufferedWriter, io.TextIOWrapper]`

open_legacy(path: `str`, mode: `str` = 'r') -> `FileHandle`

read_dir(path: `str`) -> `List[DirEntry]`

read_file(path: `str`) -> `bytes`

read_symlink(link_path: `str`) -> `str`

truncate(path: `str`, size: `int`) -> `None`

unlock_all_byte_ranges(handle_id: `int`) -> `None`

unlock_byte_range(handle_id: `int`, offset: `int`, length: `int`) -> `None`

write_file(path: `str`, data: `bytes`) -> `None`