`uio` – Input/Output stream functions¶

This module contains functions and types to work with file objects and other objects similar to files.

Differences to CPython

This module implements a simplified conceptual hierarchy of stream base classes when compared to the CPython implementation.

CPython defines a number of base stream classes which serve as the foundation for the behaviour of the main classes. The SR OS implementation does not define these abstract base classes.

Returned object types¶

The open() function can be used to open a file. Based on the arguments used when this function is called, either a TextIO or a FileIO object is returned. In both cases, the object has the same set of functions defined, but may have different behaviors depending on the type of object.

All functions are documented based on the TextIO class, however, they also apply to the FileIO class. Any differences are documented explicitly.

Functions¶

uio.open(name, mode='r', buffering=-1, newline=None)¶

Open a file. The builtin open() function is aliased to this function.

Open a file and return a corresponding file object.

Parameters

name (bytes or str) – Absolute name and path to the file that is opened.
mode (str, optional) – Mode in which the file is opened. Supported file modes are shown in the Supported file modes section. Default r which is a synonym of rt (open for reading text).
buffering (int, optional) – Set the buffering policy. 0 disables buffering (only allowed in binary mode). An integer > 0 indicates the size, in bytes, of a fixed-size chunk buffer. When no buffering argument is given, the file is buffered in chunks.
newline (None or str, optional) – Control the behavior of universal newlines mode. Only applies to TextIO mode. Accepted options: None, empty string, \n, \r, and \r\n. See the Newline behavior section for more information.

Returns

File object. The type of file object returned by the open() function depends on the mode. When open() is used to open a file in a text mode (w, r, wt, rt, etc.), it returns an instance of uio.TextIO. When used to open a file in a binary mode an instance of uio.FileIO is returned, regardless of buffering mode.

Return type

TextIO or FileIO

Raises

OSError – File cannot be opened.

Supported file modes¶

The supported file modes for SR OS are:

Character

Meaning

r

Open for reading (Default)

w

Open for writing, truncating the file first

a

Open for writing, appending to the end of file if it exists

b

Binary mode

t

Text mode (Default)

+

Open for updating (reading and writing)

Note

The default mode is r which is a synonym of rt (open for reading text). Other common values are w for writing (truncating the file if it already exists) and a for appending.

Note

Modes w+ and w+b open and truncate the file. Modes r+ and r+b open the file with no truncation.

Python distinguishes between binary and text I/O.

Files opened in binary mode (including b in the mode argument of the open() function) return data as bytes objects without any decoding.

Files opened in text mode (which is the default, or when t is explicitly included in the mode argument of the open() function) are returned as str, the bytes having been first decoded as UTF-8.

Newline behavior¶

The behavior of newlines in the open() function depends on the input provided to the newline argument.

When reading input from the stream:

If the newline argument is set to None, universal newlines mode is enabled. Lines in the input can end in \n, \r or \r\n. These are translated into \n before being returned to the caller.
If the newline argument is set to an empty string, universal newlines mode is enabled, however, line endings are returned to the caller without translation.
If the newline argument has any other legal values, input lines are only terminated by the given string and the line ending is returned to the caller without translation.

When writing output to the stream:

If the newline argument is None, any \n characters written are translated to the system default line separator, os.linesep.
If the newline argument is an empty string or \n, no translation takes place.
If the newline argument is any other legal value, any \n characters written are translated to the given string.

Classes¶

Note

Where a method definition has a / as the last argument, the method takes only positional arguments. See PEP 570 for more details.

class uio.TextIO¶

Text mode object obtained by using the open() function, for example open(name, "rt").

Warning

This class cannot be instantiated directly. Use the open() function.

read(size=-1, /)¶

Read at most size characters from stream. If size is a negative number or omitted, read until the end of the file (EOF).

Parameters: size (int, optional) – Maximum number of characters to read from the stream. Default -1.
Raises: OSError – File is not readable.

readinto(b, size=None, /)¶

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

Parameters

b (bytes) – Pre-allocated, writable bytes-like object.
size (int, optional) – The maximum size of bytes to read from the stream. Default None.

Returns

Number of bytes read.

Return type

int

write(text, /)¶

Write the provided text to the stream.

Parameters: text (str) – String to be written to the file.
Returns: Number of characters written.
Return type: int
Raises: OSError – File is not writable.

seek(offset, whence=0, /)¶

Change the stream position to the given byte offset relative to the position indicated by whence.

Parameters

offset (int) – Byte offset from whence.
whence (int, optional) –
Starting position. Accepted values:
- 0 – Seek from the start of the stream. offset must either be a number returned by tell(), or 0. Any other offset value produces undefined behaviour.
- 1 – Seek to the current position. offset must be 0, which is a no-operation. All other values of offset are unsupported.
- 2 – Seek to the end of the stream. offset must be 0. All other values of offset are unsupported.
Default 0.

Returns

New absolute position.

Return type

int

Raises

OSError – File does not support random access.

tell()¶

Obtain the current streams position.

Returns: Current stream position.
Return type: int
Raises: OSError – File does not support random access.

flush()¶: Flush the write buffers, if applicable.

close()¶

Flush and close the IO object.

This method has no effect if the file is already closed.

writelines(lines, /)¶

Write a list of lines to stream.

Line separators are not added. It is normal for each of the lines provided to have a line separator at the end.

Parameters: lines (list) – List of lines to be written.

readline(size=-1, /)¶

Read until a newline is found or until the end of the file is reached. Return a string containing a single line.

Parameters: size (int, optional) – Maximum number of characters to be read.
Returns: A single string containing the required line. If the stream is already at the end of the file (EOF), an empty string is returned.
Return type: str

readlines(hint=-1, /)¶

Return a list of lines from the stream.

Parameters: hint (int, optional) – No more lines are read if the accumulated total size (in bytes or characters) of all the lines exceeds the value specified in hint. This can be used to control the number of lines read.
Returns: List of lines
Return type: list

readable()¶

Return whether object is opened for reading.

Returns: Whether the file is readable. True indicates that the file can be read, False indicates that it cannot.
Return type: bool

writable()¶

Return whether object is opened for writing.

Returns: Whether the file is writable. True indicates that the file can be written to, False indicates that.

seekable()¶

Return whether the object supports random access. This method may perform a test seek().

Returns: Whether the file supports random access (is seekable). True if random access is supported. False if not.

truncate(size=None, /)¶

Truncate file to size bytes.

Note

The file pointer is left unchanged.

Parameters: size (int, optional) – Size to truncate the file to. Defaults to None which is interpreted as the current seek position as reported by tell().
Returns: The new size of the file.
Raises: OSError – File does not support random access.

buffered: bool¶

closed: bool¶

mode: str¶

name: str¶

newlines: str or None¶

class uio.FileIO¶: File mode object obtained by using the open() function, for example open(name, "rb").

Warning

This class cannot be instantiated directly. Use the open() function.

Important

The same methods as defined on TextIO are supported on FileIO. Any differences are documented below.

class uio.StringIO([string])¶

In-memory file-like object for input/output use for text-mode I/O, similar to a normal file opened with t file mode (See Supported file modes for more information).

Parameters: string (str) – Initial contents of the file-like object.
Raises: OSError – File-like object cannot be created.

Important

The same methods as defined on TextIO are supported on StringIO. Any differences or additions are documented below.

class uio.BytesIO([string])¶

In-memory file-like object for input/output use for binary-mode I/O, similar to a normal file opened with the b file mode (See Supported file modes for more information).

Parameters: string (bytes) – Initial contents of the file-like object.
Raises: OSError – File-like object cannot be created.

Important

The same methods as defined on TextIO are supported on BytesIO. Any differences or additions are documented below.

class uio.StringIO(alloc_size)

Create an empty StringIO object, pre-allocated to consume alloc_size bytes. With this method, writing the specific amount of bytes does not lead to reallocation of the buffer and therefore does not result in out-of-memory or memory-fragmentation issues.

Warning

This constructor is a specific MicroPython extension and is recommended for use only in special cases and in system-level libraries. It is not recommended for use in end-user applications.

Parameters: alloc_size (bytes) – Amount of memory to pre-allocate (consume).

class uio.BytesIO(alloc_size)

Create an empty BytesIO object, pre-allocated to consume alloc_size bytes. With this method, writing the specific amount of bytes does not lead to reallocation of the buffer and therefore does not result in out-of-memory or memory-fragmentation issues.

Warning

This constructor is a specific MicroPython extension and is recommended for use only in special cases and in system-level libraries. It is not recommended for use in end-user applications.

Parameters: alloc_size (bytes) – Amount of memory to pre-allocate (consume).

uio – Input/Output stream functions¶

Returned object types¶

Functions¶

Supported file modes¶

Newline behavior¶

Classes¶

`uio` – Input/Output stream functions¶