gio-pyio Documentation

PyPI	https://pypi.python.org/pypi/gio-pyio
GitHub	https://github.com/cmkohnen/gio_pyio
Docs	https://gio-pyio.readthedocs.io/

gio_pyio API

gio_pyio.open(file, mode='r', buffering=-1, encoding=None, errors=None, newline=None, native=True)

Open the file and create a corresponding file object.

If the file cannot be opened, an OSError is raised. This behaves analog to pythons builtin open() function. See Reading and Writing Files for examples of io using python.

Parameters:

• file (Gio.File) – The file to open.

• mode (str) –

  Mode in which the file is opened. Defaults to ‘r’ which means open for reading in text mode. Other common values are ‘w’ for writing (truncating the file if it already exists), ‘x’ for exclusive creation of a new file, and ‘a’ for appending. The available modes are:

  Character	Meaning
  ’r’	open for reading (default)
  ’w’	open for writing, truncating the file first
  ’x’	create a new file and open it for writing
  ’a’	open for writing, appending to the end of the file
  ’b’	binary mode
  ’t’	text mode (default)
  ’+’	open a disk file for updating (reading and writing)

  The default value is ‘r’ (open for reading text, a synonym of ‘rt’). For binary random access, the mode ‘w+b’ opens and truncates the file to 0 bytes, while ‘r+b’ opens the file without truncation. The ‘x’ mode implies ‘w’ and raises an FileExistsError if the file already exists.

  Python distinguishes between files opened in binary and text mode. Files opened in binary mode (appending ‘b’ to the mode argument) return contents as bytes objects without any decoding. In text mode (the default, or when ‘t’ is appended to the mode argument), the contents of the file are returned as strings, the bytes having first been decoded using encoding.

• buffering (int) –

  Buffering policy. Pass 0 to switch buffering off (only allowed in binary mode), 1 to select line buffering (only usable in text mode), and an integer > 1 to indicate the size of a fixed-size chunk buffer. When no buffering argument is given.

  Files are buffered in fixed-size chunks; the size of the buffer is chosen using a heuristic trying to determine the underlying device’s blksize and falling back on io.DEFAULT_BUFFER_SIZE. The buffer will typically be 4096 or 8192 bytes long.

• encoding (str) – Encoding used to decode or encode the file. Can only be used in text mode. The default encoding is platform dependent, but any encoding supported by Python can be passed. See the codecs module for the list of supported encodings.

• errors (str) – How encoding errors are to be handled. Can not be used in binary mode. Pass ‘strict’ to raise a ValueError exception if there is an encoding error (the default of None has the same effect), or pass ‘ignore’ to ignore errors. (Note that ignoring encoding errors can lead to data loss.) See the documentation for codecs.register for a list of the permitted encoding error strings.

• newline (str) –

  How universal newlines work (only applies to text mode). Can be None, ‘’, ‘n’, ‘r’, and ‘rn’. Works as follows:

  • On input, if newline is None, universal newlines mode is enabled. Lines in the input can end in ‘n’, ‘r’, or ‘rn’, and these are translated into ‘n’ before being returned to the caller. If it is ‘’, universal newline mode is enabled, but line endings are returned to the caller untranslated. If it has any of the other legal values, input lines are only terminated by the given string, and the line ending is returned to the caller untranslated.

  • On output, if newline is None, any ‘n’ characters written are translated to the system default line separator, os.linesep. If newline is ‘’, no translation takes place. If newline is any of the other legal values, any ‘n’ characters written are translated to the given string.

• native (bool) – Try and obtain a file descriptor and use python standard io libraries. If False, the result will always be a wrapped Gio stream.

Return type:

file-like

Returns:

A new file object. When used to open a file in a text mode (‘w’, ‘r’, ‘wt’, ‘rt’, etc.), the object will be a TextIOWrapper. When used to open a file in a binary mode, the returned class varies: in read binary mode, it will be a BufferedReader; in write binary and append binary modes, it will be a BufferedWriter, and in read/write mode, it will be a BufferedRandom. If buffering is disabled, the object will either be a FileIO or StreamWrapper depending on python native libraries can be used.

Raises:

• TypeError – Invalid argument passed.

• ValueError – Invalid argument passed.

• OSError – Failed to open file.

class gio_pyio.StreamWrapper(stream)

Wrap a stream as a file object.

See Gio.open_file_like() for a convenience method to open a file as a file object. Note, that this does not implement buffering, seeking, etc. and relies on the capabilities of stream.

Parameters:

stream (stream) – A stream to be wrapped.

Raises:

TypeError – Invalid argument.

close()

Flush and close the underlying stream.

This method has no effect if the underlying stream is already closed. Once closed, any operation (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.

property closed

True if the underlying stream is closed.

fileno()

Return the underlying file descriptor if it exists.

Return type:

int

Returns:

The underlying file descriptor.

Raises:

• ValueError – If the underlying stream is closed.

• io.UnsupportedOperationException – If the underlying stream is not based on a file descriptor.

flush()

Flush the write buffers of the underlying stream if applicable.

This does nothing for read-only streams.

Raises:

ValueError – If the underlying stream is closed.

read(size=-1)

Read up to size bytes from the underlying stream and return them.

As a convenience if size is unspecified or -1, all bytes until EOF are returned. The result may be fewer bytes than requested, if EOF is reached.

Parameters:

size (int) – The amount of bytes to read from the underlying stream.

Return type:

bytes

Returns:

Bytes read from the underlying stream.

Raises:

• ValueError – If the underlying stream is closed.

• io.UnsupportedOperationException – If the underlying stream is not readable.

read1(size=-1)

Read up to size bytes from the underlying stream and return them.

As a convenience if size is unspecified or -1, all bytes until EOF are returned. The result may be fewer bytes than requested, if EOF is reached.

Parameters:

size (int) – The amount of bytes to read from the underlying stream.

Return type:

bytes

Returns:

Bytes read from the underlying stream.

Raises:

• ValueError – If the underlying stream is closed.

• io.UnsupportedOperationException – If the underlying stream is not readable.

readable()

Whether or not the stream is readable.

Rtype bool:

Returns:

Whether or not this wrapper can be read from.

readall(size=-1)

Read up to size bytes from the underlying stream and return them.

As a convenience if size is unspecified or -1, all bytes until EOF are returned. The result may be fewer bytes than requested, if EOF is reached.

Parameters:

size (int) – The amount of bytes to read from the underlying stream.

Return type:

bytes

Returns:

Bytes read from the underlying stream.

Raises:

• ValueError – If the underlying stream is closed.

• io.UnsupportedOperationException – If the underlying stream is not readable.

readinto(b)

Read bytes into a pre-allocated, writable bytes-like object b.

Parameters:

b (bytes-like) – A pre-allocated object.

Return type:

int

Returns:

Number of bytes written.

Raises:

• ValueError – If the underlying stream is closed.

• io.UnsupportedOperationException – If the underlying stream is not readable.

readinto1(b)

Read bytes into a pre-allocated, writable bytes-like object b.

Parameters:

b (bytes-like) – A pre-allocated object.

Return type:

int

Returns:

Number of bytes written.

Raises:

• ValueError – If the underlying stream is closed.

• io.UnsupportedOperationException – If the underlying stream is not readable.

seek(offset, whence=0)

Change the underlying stream position.

offset is interpreted relative to the position indicated by whence.

Parameters:

• offset (int) – Where to change the stream position to, relative to whence

• whence (int) – Reference for offset. Values are: * 0 – start of stream (the default); offset should’nt be negative * 1 – current stream position; offset may be negative * 2 – end of stream; offset is usually negative

Return type:

int

Returns:

The new absolute position of the underlying stream.

Raises:

• ValueError – If the underlying stream is closed.

• io.UnsupportedOperationException – If the underlying stream is not seekable.

seekable()

Whether or not the stream is seekable.

Return type:

bool

Returns:

Whether or not the underlying stream supports seeking.

Raises:

ValueError – If the underlying stream is closed.

tell()

Tell the current stream position.

Return type:

int

Returns:

The position of the underlying stream.

Raises:

ValueError – If the underlying stream is closed.

truncate(size=None)

Resize the underlying stream to size.

Parameters:

size (int) – The size, the stream should be set to. If None the current position is used.

Return type:

int

Returns:

The new size of the underlying stream.

Raises:

• ValueError – If the underlying stream is closed.

• io.UnsupportedOperationException – If the underlying stream can not be written to.

writable()

Wheter or not the stream can be written to.

Return type:

bool

Returns:

Whether or not this wrapper can be written to.

write(b)

Write b to the underlying stream.

Parameters:

b (bytes-like) – Content to be written to the underlying stream.

Return type:

int

Returns:

The number of bytes written to the underlying stream.

Raises:

• ValueError – If the underlying stream is closed.

• io.UnsupportedOperationException – If the underlying stream can not be written to.