stream

Streaming file interface for LucidLink files.

Provides io.RawIOBase-compatible file streams for seamless integration with Python's standard library and third-party libraries (Pandas, LangChain, PyTorch, etc.).

class

lucidlink.stream.LucidFileStream

LucidFileStream(fs_wrapper: Any, path: str, mode: str = 'rb', lock_type: str = '')

Parameter	Description
`fs_wrapper`	LucidNativeSdk::FileSystem from lucidlink_native module
`path`	Path to file within filespace
`mode`	File open mode (default: 'rb')
`lock_type`	Lock type - "" (no lock), "shared" (read), "exclusive" (write). Lock is held for lifetime of file handle and released on close.

fs_wrapper

Description: LucidNativeSdk::FileSystem from lucidlink_native module

path

Description: Path to file within filespace

mode

Description: File open mode (default: 'rb')

lock_type

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

Streaming file access for LucidLink files.

Implements Python's io.RawIOBase interface for efficient, streaming access to files in LucidLink filespaces. Compatible with standard Python I/O operations and third-party libraries that expect file-like objects.

This class provides:

Standard file operations: read, write, seek, tell, truncate
Context manager support (with statement)
Iterator support (for line in file)
Optional file locking (on-open locking)
Compatibility with: Pandas, LangChain, PyTorch, Hugging Face, etc.

Example

with filespace.fs.open("/data/file.txt", "rb") as f:    data = f.read()
with filespace.fs.open("/data/output.csv", "wb") as f:    f.write(b"column1,column2\n")    f.write(b"value1,value2\n")
# With exclusive locking for SQLite-style accesswith filespace.fs.open("/data/db.sqlite", "r+b", lock_type="exclusive") as f:    data = f.read()

property

closed: `bool`

Return whether the stream is closed.

Returns

True if stream is closed

property

mode: `str`

Return the file mode.

Returns

Mode string used to open the file

property

name: `str`

Return the file path.

Returns

Path to file within filespace

method

close() -> `None`

Close the stream and release resources.

method

fileno() -> `int`

Return underlying file descriptor.

Raises

Exception	Condition
`io.UnsupportedOperation`	LucidLink files don't have OS file descriptors

io.UnsupportedOperation

Condition: LucidLink files don't have OS file descriptors

method

isatty() -> `bool`

Return whether this is an interactive stream.

Returns

False (LucidLink files are never TTY devices)

method

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

Read up to size bytes from the stream.

Parameters

Parameter	Description
`size`	Number of bytes to read, or -1 to read entire file

size

Description: Number of bytes to read, or -1 to read entire file

Returns

Bytes read from file

Raises

Exception	Condition
`ValueError`	If stream is closed
`io.UnsupportedOperation`	If stream not opened for reading

ValueError

Condition: If stream is closed

io.UnsupportedOperation

Condition: If stream not opened for reading

method

readable() -> `bool`

Return whether the stream supports reading.

Returns

True if stream was opened for reading

method

readinto(b: `bytearray`) -> `int`

Read bytes into a pre-allocated buffer.

Parameters

Parameter	Description
`b`	Buffer to read into

b

Description: Buffer to read into

Returns

Number of bytes read; 0 at EOF

method

seek(offset: `int`, whence: `int` = 0) -> `int`

Change stream position.

Parameters

Parameter	Description
`offset`	Offset in bytes
`whence`	Reference point (0=start, 1=current, 2=end)

offset

Description: Offset in bytes

whence

Description: Reference point (0=start, 1=current, 2=end)

Returns

New absolute position

method

seekable() -> `bool`

Return whether the stream supports random access.

Returns

True (LucidLink files always support seeking)

method

tell() -> `int`

Return current stream position.

Returns

Current position in bytes

method

truncate(size: `Optional[int]` = None) -> `int`

Resize the stream to the given size.

Parameters

Parameter	Description
`size`	New size in bytes, or current position if None

size

Description: New size in bytes, or current position if None

Returns

New size

Raises

Exception	Condition
`ValueError`	If stream is closed
`io.UnsupportedOperation`	If stream not opened for writing

ValueError

Condition: If stream is closed

io.UnsupportedOperation

Condition: If stream not opened for writing

method

writable() -> `bool`

Return whether the stream supports writing.

Returns

True if stream was opened for writing

method

write(b: `bytes`) -> `int`

Write bytes to the stream.

Parameters

Parameter	Description
`b`	Bytes to write

b

Description: Bytes to write

Returns

Number of bytes written

Raises

Exception	Condition
`ValueError`	If stream is closed
`io.UnsupportedOperation`	If stream not opened for writing

ValueError

Condition: If stream is closed

io.UnsupportedOperation

Condition: If stream not opened for writing

function

lucidlink.stream.open_buffered

open_buffered(fs_wrapper: Any, path: str, mode: str = 'rb', buffer_size: int = io.DEFAULT_BUFFER_SIZE, lock_type: str = '') -> io.BufferedIOBase

Open a file with buffering for improved performance.

Parameters

Parameter	Description
`fs_wrapper`	LucidNativeSdk::FileSystem from lucidlink_native module
`path`	Path to file within filespace
`mode`	File open mode (default: 'rb')
`buffer_size`	Buffer size in bytes (default: 8192)
`lock_type`	Lock type - "" (no lock), "shared" (read), "exclusive" (write)

fs_wrapper

Description: LucidNativeSdk::FileSystem from lucidlink_native module

path

Description: Path to file within filespace

mode

Description: File open mode (default: 'rb')

buffer_size

Description: Buffer size in bytes (default: 8192)

lock_type

Description: Lock type - "" (no lock), "shared" (read), "exclusive" (write)

Returns

BufferedReader, BufferedWriter, or BufferedRandom wrapping LucidFileStream

Example

with open_buffered(fs, "/data/large.csv", "rb") as f:    for line in f:        process(line)

function

lucidlink.stream.open_text

open_text(fs_wrapper: Any, path: str, mode: str = 'r', encoding: str = 'utf-8', errors: str = 'strict', newline: Optional[str] = None, lock_type: str = '') -> io.TextIOWrapper

Open a file in text mode.

Parameters

Parameter	Description
`fs_wrapper`	LucidNativeSdk::FileSystem from lucidlink_native module
`path`	Path to file within filespace
`mode`	File open mode (default: 'r')
`encoding`	Text encoding (default: 'utf-8')
`errors`	Error handling strategy (default: 'strict')
`newline`	Newline handling (None, '', 'n', 'r', 'rn')
`lock_type`	Lock type - "" (no lock), "shared" (read), "exclusive" (write)

fs_wrapper

Description: LucidNativeSdk::FileSystem from lucidlink_native module

path

Description: Path to file within filespace

mode

Description: File open mode (default: 'r')

encoding

Description: Text encoding (default: 'utf-8')

errors

Description: Error handling strategy (default: 'strict')

newline

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

lock_type

Description: Lock type - "" (no lock), "shared" (read), "exclusive" (write)

Returns

TextIOWrapper for text-mode access

Example

with open_text(fs, "/data/report.txt", "r") as f:    for line in f:        print(line.strip())

stream

lucidlink.stream.LucidFileStream

closed: bool

Returns

mode: str

Returns

name: str

Returns

close() -> None

fileno() -> int

Raises

isatty() -> bool

Returns

read(size: int = -1) -> bytes

Parameters

Returns

Raises

readable() -> bool

Returns

readinto(b: bytearray) -> int

Parameters

Returns

seek(offset: int, whence: int = 0) -> int

Parameters

Returns

seekable() -> bool

Returns

tell() -> int

Returns

truncate(size: Optional[int] = None) -> int

Parameters

Returns

Raises

writable() -> bool

Returns

write(b: bytes) -> int

Parameters

Returns

Raises

lucidlink.stream.open_buffered

Parameters

Returns

lucidlink.stream.open_text

Parameters

Returns

closed: `bool`

mode: `str`

name: `str`

close() -> `None`

fileno() -> `int`

isatty() -> `bool`

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

readable() -> `bool`

readinto(b: `bytearray`) -> `int`

seek(offset: `int`, whence: `int` = 0) -> `int`

seekable() -> `bool`

tell() -> `int`

truncate(size: `Optional[int]` = None) -> `int`

writable() -> `bool`

write(b: `bytes`) -> `int`