pyppin.file.types¶

Type declarations for accessing files.

Classes

`FileLikeObject`()	An abstract API for something that looks like a file.
`OpenOptions`([readable, writable, create, ...])	A parsed version of all of the options sent to open().

class pyppin.file.types.FileLikeObject[source]¶

Bases: ABC

An abstract API for something that looks like a file.

This is an API that is easy to implement, rather than one that’s easy to use.

You can get the easy-to-use API – a Python IO object – by calling open() on this object.

NB that for objects that are fundamentally line-oriented, like TTYs, this API is not efficient at all, and you’re better off using those directly.

abstract property readable: bool[source]¶: Return true if it’s possible to open this file for reading.

abstract property writable: bool[source]¶: Return true if it’s possible to open this file for writing or otherwise mutate it.

property fileno: int[source]¶: Return a file descriptor, or raise an OSError.

abstract size() → int[source]¶: Return the size of the file in bytes.

abstract pread(offset: int, size: int, buffer: Optional[Union[bytearray, array, memoryview, mmap, _CData, PickleBuffer]] = None) → Tuple[int, Union[bytes, bytearray, array, memoryview, mmap, _CData, PickleBuffer]][source]¶

Read [size] bytes from absolute position [offset].

Parameters

offset – The absolute offset from which to read.
size – The maximum number of bytes to read.
buffer – If given, transfer the resulting data into this bytes-like object. If not, allocate a fresh one.

Returns

A tuple of the number of bytes read, and the object into which the data was read.

Raises

OSError if anything here is invalid, including if not self.readable. –
ValueError if a buffer was provided that was too small to read into. –

abstract pwrite(offset: int, data: Union[bytes, bytearray, array, memoryview, mmap, _CData, PickleBuffer]) → int[source]¶

Write the bytes in [data] to absolute position [offset].

Parameters

offset – The absolute offset at which to write.
data – The data to write.

Returns

The number of bytes actually written.

Raises: OSError if anything here is invalid, including if not self.writable.

abstract truncate(length: int) → int[source]¶

Truncate the file.

Parameters: length – The new length of the file. If this is >= the current length of the file, do nothing.
Returns: The new size of the file.

open(mode: str = 'r', buffering: int = -1, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None) → Union[RawIOBase, BufferedIOBase, TextIOBase][source]¶

Open a file-like object with a normal Python file API.

Apart from the ‘file’ argument, all the arguments are identical to those of the built-in function open().

Note that the ‘create’-related modes (such as x) are ignored here, since the file-like object presumably already exists!

The return type, alas, depends on the mode.

class pyppin.file.types.OpenOptions(readable: bool = False, writable: bool = False, create: bool = False, truncate: bool = False, seek_to_end: bool = False, binary: bool = False, encoding: Optional[str] = None, error_handling: Optional[str] = None, newline_handling: Optional[str] = None, line_buffering: bool = False, byte_buffering: Optional[int] = None)[source]¶

Bases: NamedTuple

A parsed version of all of the options sent to open().

See the function spec for the exact logic definition.

readable: bool[source]¶: True if the file should be opened for reading.

writable: bool[source]¶: True if the file should be opened for writing.

create: bool[source]¶: True if the file should be created if it doesn’t already exist.

truncate: bool[source]¶: True if the file should be truncated to zero length on opening.

seek_to_end: bool[source]¶: True if we should seek to the end of the file immediately after opening.

binary: bool[source]¶: True if the file should be opened in binary (rather than text) mode.

encoding: Optional[str][source]¶: The encoding to use. Always None in binary mode, and not None in text mode.

error_handling: Optional[str][source]¶: The encoding error handling mechanism. Non-None in text mode.

newline_handling: Optional[str][source]¶: The newline handling mechanism. Non-None in text mode.

line_buffering: bool[source]¶: If true, do line-level buffering on the file. Only available in text mode.

byte_buffering: Optional[int][source]¶: In binary mode, this is not None and is the size of the buffer to be used.

static parse(mode: str = 'r', buffering: int = -1, encoding: Optional[str] = None, errors: Optional[str] = None, newline: Optional[str] = None, isatty: bool = False) → OpenOptions[source]¶: Parse the mode argument of open().