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.

When a file is opened in text mode, a TextIO object is returned. This object operates on str data. When a file is opened in binary mode, a FileIO object is returned. This object operates on bytes data. The methods of each class are documented independently.

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, in both text mode and binary mode. An integer > 1 indicates the size, in bytes, of a fixed-size chunk buffer. When buffering is 1, or when no buffering argument is given, the file is buffered in chunks of a default size.

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

Returns:

Characters read from the stream.

Return type:

str

Raises:

UnsupportedOperation – 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:

UnsupportedOperation – 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.

  • UnsupportedOperation – Nonzero relative seek is unsupported.

tell()

Obtain the current stream 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()

Return a list of lines from the stream.

Returns:

List of lines

Return type:

list

Differences to CPython

CPython accepts a hint argument to limit the number of lines read. The SR OS implementation takes no arguments and always reads until the end of the file (EOF).

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

Return type:

bool

seekable()

Return whether the object supports random access.

Returns:

Whether the file supports random access (is seekable). True if random access is supported; False otherwise.

Return type:

bool

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

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

Warning

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

read(size=-1, /)

Read at most size bytes 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 bytes to read from the stream. Default -1.

Returns:

Bytes read from the stream.

Return type:

bytes

Raises:

UnsupportedOperation – 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(b, /)

Write the provided bytes to the stream.

Parameters:

b (bytes) – Bytes to be written to the file.

Returns:

Number of bytes written.

Return type:

int

Raises:

UnsupportedOperation – 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 – From the start of the stream. offset should be 0 or a positive integer.

    • 1 – From the current position. offset may be negative, or positive integer.

    • 2 – Seek to the end of the stream. offset is usually a negative integer.

    Default 0.

Returns:

New absolute position.

Return type:

int

Raises:

OSError – The file does not support random access.

tell()

Obtain the current stream 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 bytes object containing a single line.

Parameters:

size (int, optional) – Maximum number of bytes to be read.

Returns:

A single bytes object containing the requested line. If the stream is already at the end of the file (EOF), an empty bytes object is returned.

Return type:

bytes

readlines()

Return a list of lines from the stream.

Returns:

List of lines

Return type:

list

Differences to CPython

CPython accepts a hint argument to limit the number of lines read. The SR OS implementation takes no arguments and always reads until the end of the file (EOF).

readable()

Return whether object is opened for reading.

Returns:

Whether the file is readable. True indicates that the file can be read; False otherwise.

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

Return type:

bool

seekable()

Return whether the object supports random access.

Returns:

Whether the file supports random access (is seekable). True if random access is supported. False otherwise.

Return type:

bool

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.StringIO([string])
class uio.StringIO(alloc_size)

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.

  • alloc_size (int) – Amount of memory to pre-allocate.

Raises:

OSError – File-like object cannot be created.

The alloc_size constructor creates an empty StringIO object and pre-allocates alloc_size bytes. With this constructor, writing up to that many bytes does not reallocate the buffer, so it avoids out-of-memory or memory-fragmentation issues.

Warning

The alloc_size 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.

read(size=-1, /)

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

Parameters:

size (int, optional) – Maximum number of characters to read from the stream. Default -1.

Returns:

Characters read from the stream.

Return type:

str

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

Returns:

Number of characters written.

Return type:

int

seek(offset, whence=0, /)

Change the stream position to offset bytes relative to whence.

Parameters:

  • offset (int) – Byte offset from whence.

  • whence (int, optional) –

    Starting position. Accepted values:

    • 0 – From the start of the stream. offset should be 0 or a positive integer.

    • 1 – From the current position. offset may be negative, or positive integer.

    • 2 – Seek to the end of the stream. offset is usually a negative integer.

    Default 0.

Returns:

New absolute position.

Return type:

int

tell()

Obtain the current stream position.

Returns:

Current stream position.

Return type:

int

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.

readline(size=-1, /)

Read until a newline is found or until the end of the stream 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 requested line. If the stream is already at the end of the stream, an empty string is returned.

Return type:

str

getvalue()

Obtain the current contents of the underlying buffer that holds data.

Returns:

Contents of the underlying buffer.

Return type:

str

class uio.BytesIO([string])
class uio.BytesIO(alloc_size)

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.

  • alloc_size (int) – Amount of memory to pre-allocate.

Raises:

OSError – File-like object cannot be created.

The alloc_size constructor creates an empty BytesIO object and pre-allocates alloc_size bytes. With this constructor, writing up to that many bytes does not reallocate the buffer, so it avoids out-of-memory or memory-fragmentation issues.

Warning

The alloc_size 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.

read(size=-1, /)

Read at most size bytes from stream. If size is a negative number or omitted, read until the end of the stream.

Parameters:

size (int, optional) – Maximum number of bytes to read from the stream. Default -1.

Returns:

Bytes read from the stream.

Return type:

bytes

read1(size=-1, /)

Read at most size bytes from stream using at most one underlying read operation. If size is a negative number or omitted, read until the end of the stream.

Parameters:

size (int, optional) – Maximum number of bytes to read from the stream. Default -1.

Returns:

Bytes read from the stream.

Return type:

bytes

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

readinto1(b, size=None, /)

Read bytes into a pre-allocated, writable, bytes-like object b, using at most one underlying read operation.

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(b, /)

Write the provided bytes to the stream.

Parameters:

b (bytes) – Bytes to be written to the stream.

Returns:

Number of bytes written.

Return type:

int

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 – From the start of the stream. offset should be 0 or a positive integer.

    • 1 – From the current position. offset may be negative, or positive integer.

    • 2 – Seek to the end of the stream. offset is usually a negative integer.

    Default 0.

Returns:

New absolute position.

Return type:

int

tell()

Obtain the current stream position.

Returns:

Current stream position.

Return type:

int

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.

readline(size=-1, /)

Read until a newline is found or until the end of the stream is reached. Return a bytes object containing a single line.

Parameters:

size (int, optional) – Maximum number of bytes to be read.

Returns:

A single bytes object containing the requested line. If the stream is already at the end of the stream, an empty bytes object is returned.

Return type:

bytes

getvalue()

Obtain the current contents of the underlying buffer that holds data.

Returns:

Contents of the underlying buffer.

Return type:

bytes

Exceptions

exception uio.UnsupportedOperation

Exception raised when an unsupported operation is attempted on a stream.

Examples include reading from a file that is not readable, writing to a file that is not writable, or performing a nonzero relative seek on a TextIO object.

Differences to CPython

In CPython, this exception inherits from both OSError and ValueError. The SR OS implementation inherits from Exception.