1. io Text, Decimal, and Original Stream I/O Tools

The io module implements classes on top of the interpreter's built-in open() to complete file-based input and output operations.These classes are properly decomposed so that they can be reassembled for different purposes - for example, to support writing Unicode data to a network socket.

1.1 Streams in Memory

StringIO provides a convenient way to work with in-memory text using file APIs such as read(), write(), and so on.In some cases, using StringIO to construct large strings can provide better performance than some other string concatenation techniques.Stream buffers in memory are also useful for testing, and writing to real files on disk does not slow down the test suite.

Below are some standard examples of using StringIO buffers.

import io

# Writing to a buffer
output = io.StringIO()
output.write('This goes into the buffer. ')
print('And so does this.', file=output)

# Retrieve the value written
print(output.getvalue())

output.close()  # discard buffer memory

# Initialize a read buffer
input = io.StringIO('Inital value for read buffer')

# Read from the buffer
print(input.read())

This example uses read(), but you can also use the readline() and readlines() methods.The StringIO class also provides a seek() method that can be jumped in a buffer when reading text, which is useful for gyration if a forward parsing algorithm is used.

To process raw bytes instead of Unicode text, you can use BytesIO.

import io

# Writing to a buffer
output = io.BytesIO()
output.write('This goes into the buffer. '.encode('utf-8'))
output.write('ÁÇÊ'.encode('utf-8'))

# Retrieve the value written
print(output.getvalue())

output.close()  # discard buffer memory

# Initialize a read buffer
input = io.BytesIO(b'Inital value for read buffer')

# Read from the buffer
print(input.read())

The value written to the BytesIO instance must be bytes instead of str.

1.2 Packaging byte streams for text data

Raw byte streams, such as sockets, can be wrapped into a layer for string encoding and decoding, making it easier to work with text data.The TextIOWrapper class supports reading and writing.The write_through parameter disables buffering and immediately refreshes all data written to the wrapper to the underlying buffer.(

import io

# Writing to a buffer
output = io.BytesIO()
wrapper = io.TextIOWrapper(
    output,
    encoding='utf-8',
    write_through=True,
)
wrapper.write('This goes into the buffer. ')
wrapper.write('ÁÇÊ')

# Retrieve the value written
print(output.getvalue())

output.close()  # discard buffer memory

# Initialize a read buffer
input = io.BytesIO(
    b'Inital value for read buffer with unicode characters ' +
    'ÁÇÊ'.encode('utf-8')
)
wrapper = io.TextIOWrapper(input, encoding='utf-8')

# Read from the buffer
print(wrapper.read())

This example uses a BytesIO instance as a stream.Examples corresponding to bz2, http,server, and subprocess show how to use TextIOWrapper on other types of file-like objects.