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 ofrt
(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 nobuffering
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. Whenopen()
is used to open a file in a text mode (w
,r
,wt
,rt
, etc.), it returns an instance ofuio.TextIO
. When used to open a file in a binary mode an instance ofuio.FileIO
is returned, regardless of buffering mode.- Return type
- 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 toNone
, 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 isNone
, 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 exampleopen(name, "rt")
.Warning
This class cannot be instantiated directly. Use the
open()
function.- read(size=-1, /)¶
Read at most
size
characters from stream. Ifsize
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 bywhence
.- 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 bytell()
, or0
. Any other offset value produces undefined behaviour.1
– Seek to the current position.offset
must be0
, which is a no-operation. All other values ofoffset
are unsupported.2
– Seek to the end of the stream.offset
must be0
. All other values ofoffset
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 bytell()
.- 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 exampleopen(name, "rb")
.Warning
This class cannot be instantiated directly. Use the
open()
function.
- 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.
- 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.
- class uio.StringIO(alloc_size)
Create an empty
StringIO
object, pre-allocated to consumealloc_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 consumealloc_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).