Python Stream#

pw_stream: A foundational interface for streaming data

The pw_stream Python package provides utilities to read and write serial interfaces.

pw_stream.stream_readers#

Serial reader utilities.

class pw_stream.stream_readers.CancellableReader(base_obj: Any, *read_args, **read_kwargs)#

Wraps communication interfaces used for reading incoming data with the guarantee that the read request can be cancelled. Derived classes must implement the cancel_read() method.

Cancelling a read invalidates ongoing and future reads. The cancel_read() method can only be called once.

__init__(base_obj: Any, *read_args, **read_kwargs)#
Parameters:

  • base_obj – Object that offers a read() method with optional args and kwargs.

  • read_args – Arguments for base_obj.read() function.

  • read_kwargs – Keyword arguments for base_obj.read() function.

abstract cancel_read() → None#

Cancels a blocking read request and all future reads.

Can only be called once.

read() → bytes#

Reads bytes that contain parts of or full RPC packets.

class pw_stream.stream_readers.DataReaderAndExecutor(
reader: CancellableReader,
on_read_error: Callable[[Exception], None],
data_processor: Callable[[bytes], Iterable[FrameTypeT]],
frame_handler: Callable[[FrameTypeT], None],
handler_threads: int | None = 1,
)#

Reads incoming bytes, data processor that delegates frame handling.

Executing callbacks in a ThreadPoolExecutor decouples reading the input stream from handling the data. That way, if a handler function takes a long time or crashes, this reading thread is not interrupted.

__init__(
reader: CancellableReader,
on_read_error: Callable[[Exception], None],
data_processor: Callable[[bytes], Iterable[FrameTypeT]],
frame_handler: Callable[[FrameTypeT], None],
handler_threads: int | None = 1,
)#

Creates the data reader and frame delegator.

Parameters:

  • reader – Reads incoming bytes from the given transport, blocks until data is available or an exception is raised. Otherwise the reader will exit.

  • on_read_error – Called when there is an error reading incoming bytes.

  • data_processor – Processes read bytes and returns a frame-like object that the frame_handler can process.

  • frame_handler – Handles a received frame.

  • handler_threads – The number of threads in the executor pool.

start() → None#

Starts the reading process.

stop() → None#

Stops the reading process.

This requests that the reading process stop and waits for the background thread to exit.

class pw_stream.stream_readers.SelectableReader(base_obj: Any, *read_args, **read_kwargs)#

Wraps interfaces that work with select() to signal when data is received.

These interfaces must provide a fileno() method. WINDOWS ONLY: Only sockets that originate from WinSock can be wrapped. File objects are not acceptable.

__init__(base_obj: Any, *read_args, **read_kwargs)#
Parameters:

  • base_obj – Object that offers a read() method with optional args and kwargs.

  • read_args – Arguments for base_obj.read() function.

  • read_kwargs – Keyword arguments for base_obj.read() function.

cancel_read() → None#

Cancels a blocking read request and all future reads.

Can only be called once.

read() → bytes#

Reads bytes that contain parts of or full RPC packets.

class pw_stream.stream_readers.SerialReader(base_obj: Serial, *read_args, **read_kwargs)#

Wraps a serial.Serial object.

__init__(base_obj: Serial, *read_args, **read_kwargs)#
Parameters:

  • base_obj – Object that offers a read() method with optional args and kwargs.

  • read_args – Arguments for base_obj.read() function.

  • read_kwargs – Keyword arguments for base_obj.read() function.

cancel_read() → None#

Cancels a blocking read request and all future reads.

Can only be called once.

class pw_stream.stream_readers.SocketReader(base_obj: socket, *read_args, **read_kwargs)#

Wraps a socket recv() function.

__init__(base_obj: socket, *read_args, **read_kwargs)#
Parameters:

  • base_obj – Object that offers a read() method with optional args and kwargs.

  • read_args – Arguments for base_obj.read() function.

  • read_kwargs – Keyword arguments for base_obj.read() function.

read() → bytes#

Reads bytes that contain parts of or full RPC packets.

class pw_stream.stream_readers.SocketSubprocess(command: Sequence, port: int)#

Executes a subprocess and connects to it with a socket.

__init__(command: Sequence, port: int) → None#
On this page