CodecFile

class tinycompress.base.CodecFile(filename, mode='r', comp=None, decomp=None)

File-like object that handles compression/decompression.

This class provides a buffered I/O interface for reading compressed files or writing compressed output, similar to Python’s built-in file objects.

Parameters:

• filename (str | bytes | PathLike | IO) – Path to the file, or an existing file object.

• mode (str) – File open mode, similar to built-in open(). ‘r’ or ‘rb’ for reading, ‘w’/’wb’/’x’/’xb’/’a’/’ab’ for writing.

• comp (BaseCompressor | None) – Compressor instance for writing compressed data. Required for write modes.

• decomp (BaseDecompressor | None) – Decompressor instance for reading compressed data. Required for read modes.

Raises:

• ValueError – If mode is invalid or required codec is missing.

• TypeError – If filename is not a str, bytes, file, or PathLike object.

Attributes

closed

Check if the file is closed.

Methods

__init__
close	Close the file and flush any unwritten compressed data.
detach	Disconnect this buffer from its underlying raw stream and return it.
fileno	Get the file descriptor number of the underlying stream.
flush	Flush write buffers, if applicable.
isatty	Return whether this is an 'interactive' stream.
read	Read and decompress up to size bytes from the file.
read1	Read up to size decompressed bytes, using at most one call to the underlying stream.
readable	Check if the file was opened for reading.
readall	Read and decompress the entire contents of the file.
readinto	Read decompressed data directly into a pre-allocated buffer.
readinto1	Read decompressed data into a buffer, using at most one underlying read.
readline	Read and decompress a single line from the file.
readlines	Read and decompress all remaining lines from the file.
seek	Change the stream position to the given offset.
seekable	Check if the file supports seeking.
tell	Get the current file position.
truncate	Truncate file to size bytes.
writable	Check if the file was opened for writing.
write	Write and compress the contents of the buffer.
writelines	Write a list of lines to stream.

__init__(filename, mode='r', comp=None, decomp=None)

__iter__()

Implement iter(self).

__next__()

Implement next(self).

_check_open()

Verify that the file is open.

Raises:

ValueError – If the file has been closed.

_check_readable()

Verify that the file is readable.

Raises:

UnsupportedOperation – If the file was not opened in read mode.

_check_seekable()

Verify that the file supports seeking.

Raises:

UnsupportedOperation – If the file does not support seeking operations (e.g., not readable or underlying stream not seekable).

_check_writable()

Verify that the file is writable.

Raises:

UnsupportedOperation – If the file was not opened in write mode.

close()

Close the file and flush any unwritten compressed data.

If opened for writing, this will flush the compressor and write any remaining compressed data to the underlying stream before closing.

property closed: bool

Check if the file is closed.

Returns:

True if the file is closed, False if it is still open.

detach()

Disconnect this buffer from its underlying raw stream and return it.

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

fileno()

Get the file descriptor number of the underlying stream.

Returns:

File descriptor number as an integer.

Raises:

UnsupportedOperation – If the underlying stream does not support fileno.

flush()

Flush write buffers, if applicable.

This is not implemented for read-only and non-blocking streams.

isatty()

Return whether this is an ‘interactive’ stream.

Return False if it can’t be determined.

read(size=-1, /)

Read and decompress up to size bytes from the file.

Parameters:

size (int | None) – Maximum number of bytes to read. If None or negative, read until EOF.

Returns:

Decompressed data as bytes.

Raises:

• ValueError – If file is closed.

• UnsupportedOperation – If file is not readable.

read1(size=-1, /)

Read up to size decompressed bytes, using at most one call to the underlying stream.

Parameters:

size (int) – Maximum number of bytes to read. If negative, read until EOF.

Returns:

Decompressed data as bytes.

Raises:

• ValueError – If file is closed.

• UnsupportedOperation – If file is not readable.

readable()

Check if the file was opened for reading.

Returns:

True if file is readable, False otherwise.

Raises:

ValueError – If file is closed.

readall()

Read and decompress the entire contents of the file.

Returns:

All decompressed data from the file as bytes.

readinto(buffer, /)

Read decompressed data directly into a pre-allocated buffer.

Parameters:

buffer (Any) – A writable buffer to store the decompressed data.

Returns:

Number of bytes read and stored in the buffer.

Raises:

• ValueError – If file is closed.

• UnsupportedOperation – If file is not readable.

readinto1(buffer, /)

Read decompressed data into a buffer, using at most one underlying read.

Parameters:

buffer (Any) – A writable buffer to store the decompressed data.

Returns:

Number of bytes read and stored in the buffer.

Note

This implementation is equivalent to readinto() since the underlying buffered reader already handles read buffering.

readline(size=-1, /)

Read and decompress a single line from the file.

Parameters:

size (int | None) – Maximum number of bytes to read. If None or negative, read entire line.

Returns:

The next line from the file, including trailing newline if present.

Raises:

• ValueError – If file is closed.

• UnsupportedOperation – If file is not readable.

readlines(hint=-1, /)

Read and decompress all remaining lines from the file.

Parameters:

hint (int | None) – Maximum number of bytes to read. If None or negative, read all lines. This is a hint, not a strict limit.

Returns:

List of lines from the file, each including trailing newline if present.

Raises:

• ValueError – If file is closed.

• UnsupportedOperation – If file is not readable.

seek(offset, whence=0, /)

Change the stream position to the given offset.

Parameters:

• offset (int) – The offset to seek to, relative to the position specified by whence.

• whence (int) – The reference point for offset. SEEK_SET: Start of stream (default). SEEK_CUR: Current position. SEEK_END: End of stream.

Returns:

The new absolute position.

Raises:

• ValueError – If file is closed.

• UnsupportedOperation – If file is not seekable.

• ValueError – If whence is invalid.

seekable()

Check if the file supports seeking.

Returns:

True if the file is readable and the underlying stream is seekable, False otherwise.

tell()

Get the current file position.

Returns:

Current position as number of bytes from start. For reading, returns position in decompressed data. For writing, returns number of bytes written.

Raises:

ValueError – If file is closed.

truncate(size=None, /)

Truncate file to size bytes.

File pointer is left unchanged. Size defaults to the current IO position as reported by tell(). Return the new size.

writable()

Check if the file was opened for writing.

Returns:

True if file is writable, False otherwise.

Raises:

ValueError – If file is closed.

write(buffer, /)

Write and compress the contents of the buffer.

Parameters:

buffer (bytes | bytearray | memoryview) – Data to be compressed and written.

Returns:

Number of uncompressed bytes written.

Raises:

• ValueError – If file is closed.

• UnsupportedOperation – If file is not writable.

writelines(lines, /)

Write a list of lines to stream.

Line separators are not added, so it is usual for each of the lines provided to have a line separator at the end.