Seekable I/O Object

pcapkit.corekit.io contains seekable I/O object SeekableReader, which is a customised implementation to io.BufferedReader.

class pcapkit.corekit.io.SeekableReader(raw, buffer_size=8192, 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 (Optional[str]) – 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.

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]

writeable()

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

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: :rtype: int

• 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.

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). The current stream position isn’t changed. This resizing can extend or reduce the current file size. In case of extension, the contents of the new file area depend on the platform (on most systems, additional bytes are zero-filled). The new file size is returned.

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.

Return type:

None

flush()

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

Return type:

None

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