4.9. Hooks#
- class caterpillar.fields.hook.IOHook(io: RawIOBase | None, init: _ContextLambda[None] | None = None, update: Callable[[bytes, _ContextLike], bytes | None] | None = None, read: Callable[[bytes, _ContextLike], bytes | None] | None = None, write: Callable[[bytes, _ContextLike], bytes | None] | None = None, finish: _ContextLambda[None] | None = None)[source]#
A custom I/O stream wrapper that allows hooks to be installed for various stages of stream interaction, such as initialization, reading and writing.
This class can be used to augment the functionality of an existing stream (e.g., file streams, memory buffers, or network sockets) by attaching custom logic for handling data as it is read or written.
- Parameters:
io (RawIOBase) – The underlying I/O stream to which the hooks are applied.
init (Optional[HookInit]) – Optional hook function to be called during initialization.
update (Optional[HookUpdate]) – Optional hook function to modify data before or after reading/writing.
read (Optional[HookRead]) – Optional hook function to be applied to data after reading.
write (Optional[HookWrite]) – Optional hook function to be applied to data before writing.
finish (Optional[HookFinish]) – Optional hook function to be called when the stream is finished.
- assert_context_set() None[source]#
Ensures that the context has been set before any I/O operations are performed.
- Raises:
ValueError – If the context is not set.
- init(context: _ContextLike) None[source]#
Initialize the I/O hook with the provided context. This triggers the init hook, if available, and sets up the context for subsequent operations.
- Parameters:
context (_ContextLike) – The context to be used for initializing the stream.
- finish(context: _ContextLike) None[source]#
Finalize the I/O hook by calling the finish hook (if provided) and restoring the original I/O stream in the context.
- Parameters:
context (_ContextLike) – The context used during the finalization.
- seekable() bool[source]#
Checks if the underlying I/O stream is seekable.
- Returns:
True if the stream supports seeking, otherwise False.
- Return type:
bool
- readable() bool[source]#
Checks if the underlying I/O stream is readable.
- Returns:
True if the stream supports reading, otherwise False.
- Return type:
bool
- read(size: int = -1) bytes | None[source]#
Read data from the stream, applying the optional hooks (if any).
The update hook, if provided, will be called to modify the data.
The read hook, if provided, will be called to further modify the data.
- Parameters:
size (int) – The number of bytes to read, defaults to -1 (read until EOF).
- Returns:
The read data, possibly modified by the hooks.
- Return type:
Union[bytes, None]
- write(b: Buffer, /) int[source]#
Write data to the stream, applying the optional hooks (if any).
The update hook, if provided, will be called to modify the data before writing.
The write hook, if provided, will be called to modify the data before the final write operation.
- Parameters:
b (bytes) – The data to write.
- Returns:
The number of bytes written to the underlying stream.
- Return type:
Union[int, None]
- writable() bool[source]#
Checks if the underlying I/O stream is writable.
- Returns:
True if the stream supports writing, otherwise False.
- Return type:
bool