io::TextStream class

The TextStream class represents an encoded text stream.

See also: The encodings module defines several encoding classes.

class TextStream(stream[, encoding], ...)

Construct an encoded text stream. The stream argument should conform to the Stream interface. It is used for reading and writing the encoded (narrow) text data, i.e. the TextStream object wraps this stream. This class is typically used for reading and writing Unicode text using narrow (8-bit) streams. If the encoding is not specified, the encoding will be DefaultEncoding.

The optional arguments may include a buffering argument that defines the buffering mode (Buffered, LineBuffered or Unbuffered) and either encodings::Strict or encodings::Unstrict. The default options are Buffered and Strict.

TextStream inherits from Stream. All input and output operations return and expect Unicode encoded strings. If an attempt is made to write a character that cannot be represented by the stream encoding, an encodings::EncodeError exception will be raised.

Note: When using buffering, reporting of encoding errors may be delayed. Errors are reported only when the buffer is actually written to the wrapped stream.

TextStream methods

TextStream does not define any additional methods over those inherited from Stream. A single method has a significantly different behavior in TextStream than in Stream:

close()

Close the stream by flushing the output buffers and closing the wrapped stream. Any stream operations other than close made to a closed TextStream object will fail.