Seekable I/O Object

pcapkit.corekit.io contains SeekableReader, a seekable customisation of io.BufferedReader.

class pcapkit.corekit.io.SeekableReader(raw, buffer_size=131072, buffer_save=False, buffer_path=None, *, stream_closing=True)

Bases: BufferedReader

Seekable buffered reader.

A buffered binary stream providing higher-level access to a readable, non seekable RawIOBase raw binary stream. It inherits BufferedIOBase.

When reading data from this object, a larger amount of data may be requested from the underlying raw stream, and kept in an internal buffer. The buffered data can then be returned directly on subsequent reads.

The constructor creates a BufferedReader for the given readable raw stream and buffer_size. If buffer_size is omitted, DEFAULT_BUFFER_SIZE is used.

Parameters:

• raw (IO[bytes]) – Underlying raw stream.

• buffer_size (int) – Buffer size.

• buffer_save (bool) – Whether to save buffer to file.

• buffer_path (str | None) – Path to save buffer.

• stream_closing (bool) – Whether the stream should be closed upon exiting.

property raw: RawIOBase

The underlying raw stream (a RawIOBase instance) that BufferedIOBase deals with. This is not part of the BufferedIOBase API and may not exist on some implementations.

property closed: bool

True if the stream is closed.

_stream: IO[bytes]

Underlying raw stream.

_closed: bool

Whether the stream is closed.

read(size=-1, /)

Read and return size bytes, or if size is not given or negative, until EOF or if the read call would block in non-blocking mode.

Return type:

bytes

read1(size=-1, /)

Read and return up to size bytes with only one call on the raw stream. If at least one byte is buffered, only buffered bytes are returned. Otherwise, one raw stream read call is made.

Return type:

bytes

readinto(b, /)

Read bytes into a pre-allocated, writable bytes-like object b and return the number of bytes read. For example, b might be a bytearray.

Like read(), multiple reads may be issued to the underlying raw stream, unless the latter is interactive.

A BlockingIOError is raised if the underlying raw stream is in non blocking-mode, and has no data available at the moment.

Return type:

int

readinto1(b, /)

Read bytes into a pre-allocated, writable bytes-like object b, using at most one call to the underlying raw stream’s read() (or readinto()) method. Return the number of bytes read.

A BlockingIOError is raised if the underlying raw stream is in non blocking-mode, and has no data available at the moment.

Return type:

int

readable()

Return True if the stream can be read from. If False, read() will raise OSError.

Return type:

bool

readline(size=-1, /)

Read and return one line from the stream. If size is specified, at most size bytes will be read.

The line terminator is always b'\n' for binary files; for text files, the newline argument to open() can be used to select the line terminator(s) recognized.

Return type:

bytes

readlines(hint=-1, /)

Read and return a list of lines from the stream. hint can be specified to control the number of lines read: no more lines will be read if the total size (in bytes/characters) of all lines so far exceeds hint.

hint values of 0 or less, as well as None, are treated as no hint.

Note that it’s already possible to iterate on file objects using for line in file: ... without calling file.readlines().

Return type:

list[bytes]

writable()

Return True if the stream supports writing. If False, write() and truncate() will raise OSError.

Note

This was spelled writeable until #645, which is not how the io protocol spells it, so it overrode nothing and io never consulted it – the inherited io.IOBase.writable() answered instead. Both returned False, so there was no observable divergence to notice; the coincidence is what hid it.

Return type:

bool

write(b, /)

Write the given bytes-like object, b, and return the number of bytes written (always equal to the length of b in bytes, since if the write fails an OSError will be raised). Depending on the actual implementation, these bytes may be readily written to the underlying stream, or held in a buffer for performance and latency reasons.

When in non-blocking mode, a BlockingIOError is raised if the data needed to be written to the raw stream but it couldn’t accept all the data without blocking.

The caller may release or mutate b after this method returns, so the implementation should only access b during the method call.

Return type:

int

seekable()

Return True if the stream supports random access. If False, seek(), tell() and truncate() will raise OSError.

Return type:

bool

seek(offset, whence=0, /)

Change the stream position to the given byte offset. offset is interpreted relative to the position indicated by whence. The default value for whence is SEEK_SET. Values for whence are:

• SEEK_SET or 0 - start of the stream (the default); offset should be zero or positive

• SEEK_CUR or 1 - current stream position; offset may be negative

• SEEK_END or 2 - end of the stream; offset is usually negative

Return the new absolute position.

Note

The target is computed, then validated, and only then written to _tell. A branch that assigned the position before deciding whether to accept it left a refused seek having moved it anyway, with the resync below – the one thing that puts the buffer’s cursor back in step – skipped on the way out. A caller that catches the error and reasonably takes the position to be unchanged then read from the rejected offset instead, silently and without a second error.

The negative check applies to every whence, rather than only SEEK_SET looking at its offset. An absolute position below zero cannot exist under any of them, and it is not the same failure as a position that has merely slid out of the window – which is ordinary, and recoverable with buffer_save=True. Reporting the first as negative seek value keeps the two distinguishable, and being a property of the position rather than of the window it holds with a saved buffer as well, where the old refusal did not apply at all and the seek returned a negative position as if it had worked.

Return type:

int

tell()

Return the current stream position.

Return type:

int

truncate(size=None, /)

Resize the stream to the given size in bytes (or the current position if size is not specified).

Raises:

UnsupportedOperation – Always, since the reader is not writable.

Note

io.IOBase.writable() gates this method as well as write() – “If False, write() and truncate() will raise OSError” – and writable() here returns False, so refusing is what the contract asks for. It is also what CPython’s own read-only buffered readers do: both the accelerated io.BufferedReader and the pure-Python _pyio.BufferedReader raise io.UnsupportedOperation, the latter from _BufferedIOMixin.truncate’s _checkWritable() (#645).

The resizing this used to perform is still reachable internally, as _truncate_buffer(). It never touched the underlying stream in the first place – it resizes a private lookback window – which is why it survives under a private name rather than being removed with the public method’s behaviour.

Return type:

int

close()

Flush and close this stream. This method has no effect if the file is already closed. Once the file is closed, any operation on the file (e.g. reading or writing) will raise a ValueError.

As a convenience, it is allowed to call this method more than once; only the first call, however, will have an effect.

flush()

Flush the write buffers of the stream if applicable. This does nothing for read-only and non-blocking streams.

peek(size=0)

Return bytes from the stream without advancing the position.

At most one single read on the raw stream is done to satisfy the call. The number of bytes returned may be less or more than requested.

Return type:

bytes

detach()

Separate the underlying raw stream from the buffer and return it.

After the raw stream has been detached, the buffer is in an unusable state.

Some buffers, like BytesIO, do not have the concept of a single raw stream to return from this method. They raise UnsupportedOperation.

Return type:

RawIOBase

fileno()

Return the underlying file descriptor (an integer) of the stream if it exists. An OSError is raised if the IO object does not use a file descriptor.

Return type:

int

isatty()

Return True if the stream is interactive (i.e., connected to a terminal/tty device).

Return type:

bool