New in version 2.6.

Note

Since this module has been designed primarily for Python 3.x, you have tobe aware that all uses of “bytes” in this document refer to thestr type (of whichbytes is an alias), and all usesof “text” refer to theunicode type. Furthermore, those twotypes are not interchangeable in theio APIs.

15.2.1.Module Interface¶

io.DEFAULT_BUFFER_SIZE¶

An int containing the default buffer size used by the module’s buffered I/Oclasses.open() uses the file’s blksize (as obtained byos.stat()) if possible.

io.open(file,mode='r',buffering=-1,encoding=None,errors=None,newline=None,closefd=True)¶

Openfile and return a corresponding stream. If the file cannot be opened,anIOError is raised.

file is either a string giving the pathname (absolute orrelative to the current working directory) of the file to be opened oran integer file descriptor of the file to be wrapped. (If a file descriptoris given, it is closed when the returned I/O object is closed, unlessclosefd is set toFalse.)

mode is an optional string that specifies the mode in which the file isopened. It defaults to'r' which means open for reading in text mode.Other common values are'w' for writing (truncating the file if italready exists), and'a' for appending (which onsome Unix systems,means thatall writes append to the end of the file regardless of thecurrent seek position). In text mode, ifencoding is not specified theencoding used is platform dependent. (For reading and writing raw bytes usebinary mode and leaveencoding unspecified.) The available modes 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 the file if it exists
'b'	binary mode
't'	text mode (default)
'+'	open a disk file for updating (reading and writing)
'U'	universal newlines mode (for backwards compatibility; shouldnot be used in new code)

The default mode is'rt' (open for reading text). For binary randomaccess, the mode'w+b' opens and truncates the file to 0 bytes, while'r+b' opens the file without truncation.

Python distinguishes between files opened in binary and text modes, even whenthe underlying operating system doesn’t. Files opened in binary mode(including'b' in themode argument) return contents asbytesobjects without any decoding. In text mode (the default, or when't' isincluded in themode argument), the contents of the file are returned asunicode strings, the bytes having been first decoded using aplatform-dependent encoding or using the specifiedencoding if given.

buffering is an optional integer used to set the buffering policy.Pass 0 to switch buffering off (only allowed in binary mode), 1 to selectline buffering (only usable in text mode), and an integer > 1 to indicatethe size of a fixed-size chunk buffer. When nobuffering argument isgiven, the default buffering policy works as follows:

• Binary files are buffered in fixed-size chunks; the size of the bufferis chosen using a heuristic trying to determine the underlying device’s“block size” and falling back onDEFAULT_BUFFER_SIZE.On many systems, the buffer will typically be 4096 or 8192 bytes long.

• “Interactive” text files (files for whichisatty() returns True)use line buffering. Other text files use the policy described abovefor binary files.

encoding is the name of the encoding used to decode or encode the file.This should only be used in text mode. The default encoding is platformdependent (whateverlocale.getpreferredencoding() returns), but anyencoding supported by Python can be used. See thecodecs module forthe list of supported encodings.

errors is an optional string that specifies how encoding and decodingerrors are to be handled—this cannot be used in binary mode. Pass'strict' to raise aValueError exception if there is an encodingerror (the default ofNone has the same effect), or pass'ignore' toignore errors. (Note that ignoring encoding errors can lead to data loss.)'replace' causes a replacement marker (such as'?') to be insertedwhere there is malformed data. When writing,'xmlcharrefreplace'(replace with the appropriate XML character reference) or'backslashreplace' (replace with backslashed escape sequences) can beused. Any other error handling name that has been registered withcodecs.register_error() is also valid.

newline controls howuniversal newlines works (it only applies totext mode). It can beNone,'','\n','\r', and'\r\n'.It works as follows:

• On input, ifnewline isNone, universal newlines mode is enabled.Lines in the input can end in'\n','\r', or'\r\n', and theseare translated into'\n' before being returned to the caller. If it is'', universal newlines mode is enabled, but line endings are returned tothe caller untranslated. If it has any of the other legal values, inputlines are only terminated by the given string, and the line ending isreturned to the caller untranslated.

• On output, ifnewline isNone, any'\n' characters written aretranslated to the system default line separator,os.linesep. Ifnewline is'', no translation takes place. Ifnewline is any ofthe other legal values, any'\n' characters written are translated tothe given string.

Ifclosefd isFalse and a file descriptor rather than a filename wasgiven, the underlying file descriptor will be kept open when the file isclosed. If a filename is givenclosefd has no effect and must beTrue(the default).

The type of file object returned by theopen() function depends on themode. Whenopen() is used to open a file in a text mode ('w','r','wt','rt', etc.), it returns a subclass ofTextIOBase (specificallyTextIOWrapper). When used to opena file in a binary mode with buffering, the returned class is a subclass ofBufferedIOBase. The exact class varies: in read binary mode, itreturns aBufferedReader; in write binary and append binary modes,it returns aBufferedWriter, and in read/write mode, it returns aBufferedRandom. When buffering is disabled, the raw stream, asubclass ofRawIOBase,FileIO, is returned.

It is also possible to use anunicode orbytes stringas a file for both reading and writing. Forunicode stringsStringIO can be used like a file opened in text mode,and forbytes aBytesIO can be used like afile opened in a binary mode.

exceptionio.BlockingIOError¶

Error raised when blocking would occur on a non-blocking stream. It inheritsIOError.

In addition to those ofIOError,BlockingIOError has oneattribute:

characters_written¶

An integer containing the number of characters written to the streambefore it blocked.

exceptionio.UnsupportedOperation¶

An exception inheritingIOError andValueError that is raisedwhen an unsupported operation is called on a stream.

15.2.2.I/O Base Classes¶

classio.IOBase¶

The abstract base class for all I/O classes, acting on streams of bytes.There is no public constructor.

This class provides empty abstract implementations for many methodsthat derived classes can override selectively; the defaultimplementations represent a file that cannot be read, written orseeked.

Even thoughIOBase does not declareread(),readinto(),orwrite() because their signatures will vary, implementations andclients should consider those methods part of the interface. Also,implementations may raise anIOError when operations they do notsupport are called.

The basic type used for binary data read from or written to a file isbytes (also known asstr). Method arguments mayalso bebytearray ormemoryview of arrays of bytes.In some cases, such asreadinto(), a writable objectsuch asbytearray is required.Text I/O classes work withunicode data.

Changed in version 2.7:Implementations should supportmemoryview arguments.

Note that calling any method (even inquiries) on a closed stream isundefined. Implementations may raiseIOError in this case.

IOBase (and its subclasses) support the iterator protocol, meaning that anIOBase object can be iterated over yielding the lines in a stream.Lines are defined slightly differently depending on whether the stream isa binary stream (yieldingbytes), or a text stream (yieldingunicode strings). Seereadline() below.

IOBase is also a context manager and therefore supports thewith statement. In this example,file is closed after thewith statement’s suite is finished—even if an exception occurs:

withio.open('spam.txt','w')asfile:file.write(u'Spam and eggs!')

IOBase provides these data attributes and methods:

close()¶

Flush and close this stream. This method has no effect if the file isalready closed. Once the file is closed, any operation on the file(e.g. reading or writing) will raise aValueError.

As a convenience, it is allowed to call this method more than once;only the first call, however, will have an effect.

closed¶

True if the stream is closed.

fileno()¶

Return the underlying file descriptor (an integer) of the stream if itexists. AnIOError is raised if the IO object does not use a filedescriptor.

flush()¶

Flush the write buffers of the stream if applicable. This does nothingfor read-only and non-blocking streams.

isatty()¶

ReturnTrue if the stream is interactive (i.e., connected toa terminal/tty device).

readable()¶

ReturnTrue if the stream can be read from. IfFalse,read()will raiseIOError.

readline(limit=-1)¶

Read and return one line from the stream. Iflimit is specified, atmostlimit bytes will be read.

The line terminator is alwaysb'\n' for binary files; for text files,thenewline argument toopen() can be used to select the lineterminator(s) recognized.

readlines(hint=-1)¶

Read and return a list of lines from the stream.hint can be specifiedto control the number of lines read: no more lines will be read if thetotal size (in bytes/characters) of all lines so far exceedshint.

Note that it’s already possible to iterate on file objects usingforlineinfile:... without callingfile.readlines().

seek(offset,whence=SEEK_SET)¶

Change the stream position to the given byteoffset.offset isinterpreted relative to the position indicated bywhence. The defaultvalue forwhence isSEEK_SET. Values forwhence are:

• SEEK_SET or0 – start of the stream (the default);offset should be zero or positive

• SEEK_CUR or1 – current stream position;offset maybe negative

• SEEK_END or2 – end of the stream;offset is usuallynegative

Return the new absolute position.

New in version 2.7:TheSEEK_* constants

seekable()¶

ReturnTrue if the stream supports random access. IfFalse,seek(),tell() andtruncate() will raiseIOError.

tell()¶

Return the current stream position.

truncate(size=None)¶

Resize the stream to the givensize in bytes (or the current positionifsize is not specified). The current stream position isn’t changed.This resizing can extend or reduce the current file size. In case ofextension, the contents of the new file area depend on the platform(on most systems, additional bytes are zero-filled, on Windows they’reundetermined). The new file size is returned.

writable()¶

ReturnTrue if the stream supports writing. IfFalse,write() andtruncate() will raiseIOError.

writelines(lines)¶

Write a list of lines to the stream. Line separators are not added, so itis usual for each of the lines provided to have a line separator at theend.

__del__()¶

Prepare for object destruction.IOBase provides a defaultimplementation of this method that calls the instance’sclose() method.

classio.RawIOBase¶

Base class for raw binary I/O. It inheritsIOBase. There is nopublic constructor.

Raw binary I/O typically provides low-level access to an underlying OSdevice or API, and does not try to encapsulate it in high-level primitives(this is left to Buffered I/O and Text I/O, described later in this page).

In addition to the attributes and methods fromIOBase,RawIOBase provides the following methods:

read(n=-1)¶

Read up ton bytes from the object and return them. As a convenience,ifn is unspecified or -1,readall() is called. Otherwise,only one system call is ever made. Fewer thann bytes may bereturned if the operating system call returns fewer thann bytes.

If 0 bytes are returned, andn was not 0, this indicates end of file.If the object is in non-blocking mode and no bytes are available,None is returned.

readall()¶

Read and return all the bytes from the stream until EOF, using multiplecalls to the stream if necessary.

readinto(b)¶

Read up to len(b) bytes intob, and return the numberof bytes read. The objectb should be a pre-allocated, writablearray of bytes, eitherbytearray ormemoryview.If the object is in non-blocking mode and nobytes are available,None is returned.

write(b)¶

Writeb to the underlying raw stream, and return thenumber of bytes written. The objectb should be an arrayof bytes, eitherbytes,bytearray, ormemoryview. The return value can be less thanlen(b), depending on specifics of the underlying raw stream, andespecially if it is in non-blocking mode.None is returned if theraw stream is set not to block and no single byte could be readilywritten to it. The caller may release or mutateb afterthis method returns, so the implementation should only accessbduring the method call.

classio.BufferedIOBase¶

Base class for binary streams that support some kind of buffering.It inheritsIOBase. There is no public constructor.

The main difference withRawIOBase is that methodsread(),readinto() andwrite() will try (respectively) to read as muchinput as requested or to consume all given output, at the expense ofmaking perhaps more than one system call.

In addition, those methods can raiseBlockingIOError if theunderlying raw stream is in non-blocking mode and cannot take or giveenough data; unlike theirRawIOBase counterparts, they willnever returnNone.

Besides, theread() method does not have a defaultimplementation that defers toreadinto().

A typicalBufferedIOBase implementation should not inherit from aRawIOBase implementation, but wrap one, likeBufferedWriter andBufferedReader do.

BufferedIOBase provides or overrides these methods and attribute inaddition to those fromIOBase:

raw¶

The underlying raw stream (aRawIOBase instance) thatBufferedIOBase deals with. This is not part of theBufferedIOBase API and may not exist on some implementations.

detach()¶

Separate the underlying raw stream from the buffer and return it.

After the raw stream has been detached, the buffer is in an unusablestate.

Some buffers, likeBytesIO, do not have the concept of a singleraw stream to return from this method. They raiseUnsupportedOperation.

New in version 2.7.

read(n=-1)¶

Read and return up ton bytes. If the argument is omitted,None, ornegative, data is read and returned until EOF is reached. An empty bytesobject is returned if the stream is already at EOF.

If the argument is positive, and the underlying raw stream is notinteractive, multiple raw reads may be issued to satisfy the byte count(unless EOF is reached first). But for interactive raw streams, at mostone raw read will be issued, and a short result does not imply that EOF isimminent.

ABlockingIOError is raised if the underlying raw stream is innon blocking-mode, and has no data available at the moment.

read1(n=-1)¶

Read and return up ton bytes, with at most one call to the underlyingraw stream’sread() method. This can be useful if youare implementing your own buffering on top of aBufferedIOBaseobject.

readinto(b)¶

Read up to len(b) bytes intob, and return the number of bytes read.The objectb should be a pre-allocated, writable array of bytes,eitherbytearray ormemoryview.

Likeread(), multiple reads may be issued to the underlying rawstream, unless the latter is ‘interactive’.

ABlockingIOError is raised if the underlying raw stream is innon blocking-mode, and has no data available at the moment.

write(b)¶

Writeb, and return the number of bytes written(always equal tolen(b), since if the write failsanIOError will be raised). The objectb should bean array of bytes, eitherbytes,bytearray,ormemoryview. Depending on the actualimplementation, these bytes may be readily written to the underlyingstream, or held in a buffer for performance and latency reasons.

When in non-blocking mode, aBlockingIOError is raised if thedata needed to be written to the raw stream but it couldn’t acceptall the data without blocking.

The caller may release or mutateb after this method returns,so the implementation should only accessb during the method call.

15.2.3.Raw File I/O¶

classio.FileIO(name,mode='r',closefd=True)¶

FileIO represents an OS-level file containing bytes data.It implements theRawIOBase interface (and therefore theIOBase interface, too).

Thename can be one of two things:

• a string representing the path to the file which will be opened;

• an integer representing the number of an existing OS-level file descriptorto which the resultingFileIO object will give access.

Themode can be'r','w' or'a' for reading (default), writing,or appending. The file will be created if it doesn’t exist when opened forwriting or appending; it will be truncated when opened for writing. Add a'+' to the mode to allow simultaneous reading and writing.

Theread() (when called with a positive argument),readinto()andwrite() methods on this class will only make one system call.

In addition to the attributes and methods fromIOBase andRawIOBase,FileIO provides the following dataattributes and methods:

mode¶

The mode as given in the constructor.

name¶

The file name. This is the file descriptor of the file when no name isgiven in the constructor.

15.2.4.Buffered Streams¶

Buffered I/O streams provide a higher-level interface to an I/O devicethan raw I/O does.

classio.BytesIO([initial_bytes])¶

A stream implementation using an in-memory bytes buffer. It inheritsBufferedIOBase.

The optional argumentinitial_bytes is abytes object thatcontains initial data.

BytesIO provides or overrides these methods in addition to thosefromBufferedIOBase andIOBase:

getvalue()¶

Returnbytes containing the entire contents of the buffer.

read1()¶

InBytesIO, this is the same asread().

classio.BufferedReader(raw,buffer_size=DEFAULT_BUFFER_SIZE)¶

A buffer providing higher-level access to a readable, sequentialRawIOBase object. It inheritsBufferedIOBase.When reading data from this object, a larger amount of data may berequested from the underlying raw stream, and kept in an internal buffer.The buffered data can then be returned directly on subsequent reads.

The constructor creates aBufferedReader for the given readableraw stream andbuffer_size. Ifbuffer_size is omitted,DEFAULT_BUFFER_SIZE is used.

BufferedReader provides or overrides these methods in addition tothose fromBufferedIOBase andIOBase:

peek([n])¶

Return bytes from the stream without advancing the position. At most onesingle read on the raw stream is done to satisfy the call. The number ofbytes returned may be less or more than requested.

read([n])¶

Read and returnn bytes, or ifn is not given or negative, until EOFor if the read call would block in non-blocking mode.

read1(n)¶

Read and return up ton bytes with only one call on the raw stream. Ifat least one byte is buffered, only buffered bytes are returned.Otherwise, one raw stream read call is made.

classio.BufferedWriter(raw,buffer_size=DEFAULT_BUFFER_SIZE)¶

A buffer providing higher-level access to a writeable, sequentialRawIOBase object. It inheritsBufferedIOBase.When writing to this object, data is normally held into an internalbuffer. The buffer will be written out to the underlyingRawIOBaseobject under various conditions, including:

• when the buffer gets too small for all pending data;

• whenflush() is called;

• when aseek() is requested (forBufferedRandom objects);

• when theBufferedWriter object is closed or destroyed.

The constructor creates aBufferedWriter for the given writeableraw stream. If thebuffer_size is not given, it defaults toDEFAULT_BUFFER_SIZE.

A third argument,max_buffer_size, is supported, but unused and deprecated.

BufferedWriter provides or overrides these methods in addition tothose fromBufferedIOBase andIOBase:

flush()¶

Force bytes held in the buffer into the raw stream. ABlockingIOError should be raised if the raw stream blocks.

write(b)¶

Writeb, and return the number of bytes written.The objectb should be an array of bytes, eitherbytes,bytearray, ormemoryview.When in non-blocking mode, aBlockingIOError is raisedif the buffer needs to be written out but the raw stream blocks.

classio.BufferedRandom(raw,buffer_size=DEFAULT_BUFFER_SIZE)¶

A buffered interface to random access streams. It inheritsBufferedReader andBufferedWriter, and further supportsseek() andtell() functionality.

The constructor creates a reader and writer for a seekable raw stream, givenin the first argument. If thebuffer_size is omitted it defaults toDEFAULT_BUFFER_SIZE.

A third argument,max_buffer_size, is supported, but unused and deprecated.

BufferedRandom is capable of anythingBufferedReader orBufferedWriter can do.

classio.BufferedRWPair(reader,writer,buffer_size=DEFAULT_BUFFER_SIZE)¶

A buffered I/O object combining two unidirectionalRawIOBaseobjects – one readable, the other writeable – into a single bidirectionalendpoint. It inheritsBufferedIOBase.

reader andwriter areRawIOBase objects that are readable andwriteable respectively. If thebuffer_size is omitted it defaults toDEFAULT_BUFFER_SIZE.

A fourth argument,max_buffer_size, is supported, but unused anddeprecated.

BufferedRWPair implements all ofBufferedIOBase’s methodsexcept fordetach(), which raisesUnsupportedOperation.

Warning

BufferedRWPair does not attempt to synchronize accesses toits underlying raw streams. You should not pass it the same objectas reader and writer; useBufferedRandom instead.

15.2.5.Text I/O¶

classio.TextIOBase¶

Base class for text streams. This class provides a unicode characterand line based interface to stream I/O. There is noreadinto()method because Python’sunicode strings are immutable.It inheritsIOBase. There is no public constructor.

TextIOBase provides or overrides these data attributes andmethods in addition to those fromIOBase:

encoding¶

The name of the encoding used to decode the stream’s bytes intostrings, and to encode strings into bytes.

errors¶

The error setting of the decoder or encoder.

newlines¶

A string, a tuple of strings, orNone, indicating the newlinestranslated so far. Depending on the implementation and the initialconstructor flags, this may not be available.

buffer¶

The underlying binary buffer (aBufferedIOBase instance) thatTextIOBase deals with. This is not part of theTextIOBase API and may not exist on some implementations.

detach()¶

Separate the underlying binary buffer from theTextIOBase andreturn it.

After the underlying buffer has been detached, theTextIOBase isin an unusable state.

SomeTextIOBase implementations, likeStringIO, may nothave the concept of an underlying buffer and calling this method willraiseUnsupportedOperation.

New in version 2.7.

read(n=-1)¶

Read and return at mostn characters from the stream as a singleunicode. Ifn is negative orNone, reads until EOF.

readline(limit=-1)¶

Read until newline or EOF and return a singleunicode. If thestream is already at EOF, an empty string is returned.

Iflimit is specified, at mostlimit characters will be read.

seek(offset,whence=SEEK_SET)¶

Change the stream position to the givenoffset. Behaviour depends onthewhence parameter. The default value forwhence isSEEK_SET.

• SEEK_SET or0: seek from the start of the stream(the default);offset must either be a number returned byTextIOBase.tell(), or zero. Any otheroffset valueproduces undefined behaviour.

• SEEK_CUR or1: “seek” to the current position;offset must be zero, which is a no-operation (all other valuesare unsupported).

• SEEK_END or2: seek to the end of the stream;offset must be zero (all other values are unsupported).

Return the new absolute position as an opaque number.

New in version 2.7:TheSEEK_* constants.

tell()¶

Return the current stream position as an opaque number. The numberdoes not usually represent a number of bytes in the underlyingbinary storage.

write(s)¶

Write theunicode strings to the stream and return thenumber of characters written.

classio.TextIOWrapper(buffer,encoding=None,errors=None,newline=None,line_buffering=False)¶

A buffered text stream over aBufferedIOBase binary stream.It inheritsTextIOBase.

encoding gives the name of the encoding that the stream will be decoded orencoded with. It defaults tolocale.getpreferredencoding().

errors is an optional string that specifies how encoding and decodingerrors are to be handled. Pass'strict' to raise aValueErrorexception if there is an encoding error (the default ofNone has the sameeffect), or pass'ignore' to ignore errors. (Note that ignoring encodingerrors can lead to data loss.)'replace' causes a replacement marker(such as'?') to be inserted where there is malformed data. Whenwriting,'xmlcharrefreplace' (replace with the appropriate XML characterreference) or'backslashreplace' (replace with backslashed escapesequences) can be used. Any other error handling name that has beenregistered withcodecs.register_error() is also valid.

newline controls how line endings are handled. It can beNone,'','\n','\r', and'\r\n'. It works as follows:

• On input, ifnewline isNone,universal newlines mode isenabled. Lines in the input can end in'\n','\r', or'\r\n',and these are translated into'\n' before being returned to thecaller. If it is'', universal newlines mode is enabled, but lineendings are returned to the caller untranslated. If it has any of theother legal values, input lines are only terminated by the given string,and the line ending is returned to the caller untranslated.

• On output, ifnewline isNone, any'\n' characters written aretranslated to the system default line separator,os.linesep. Ifnewline is'', no translation takes place. Ifnewline is any ofthe other legal values, any'\n' characters written are translated tothe given string.

Ifline_buffering isTrue,flush() is implied when a call towrite contains a newline character or a carriage return.

TextIOWrapper provides one attribute in addition to those ofTextIOBase and its parents:

line_buffering¶

Whether line buffering is enabled.

classio.StringIO(initial_value=u'',newline=u'\n')¶

An in-memory stream for unicode text. It inheritsTextIOWrapper.

The initial value of the buffer can be set by providinginitial_value.If newline translation is enabled, newlines will be encoded as if bywrite(). The stream is positioned at the start ofthe buffer.

Thenewline argument works like that ofTextIOWrapper.The default is to consider only\n characters as ends of lines andto do no newline translation. Ifnewline is set toNone,newlines are written as\n on all platforms, but universalnewline decoding is still performed when reading.

StringIO provides this method in addition to those fromTextIOWrapper and its parents:

getvalue()¶

Return aunicode containing the entire contents of the buffer at anytime before theStringIO object’sclose() method iscalled. Newlines are decoded as if byread(),although the stream position is not changed.

Example usage:

importiooutput=io.StringIO()output.write(u'First line.\n')output.write(u'Second line.\n')# Retrieve file contents -- this will be# u'First line.\nSecond line.\n'contents=output.getvalue()# Close object and discard memory buffer --# .getvalue() will now raise an exception.output.close()

classio.IncrementalNewlineDecoder¶

A helper codec that decodes newlines foruniversal newlines mode.It inheritscodecs.IncrementalDecoder.

15.2.6.Advanced topics¶

Here we will discuss several advanced topics pertaining to the concreteI/O implementations described above.