Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / Python

io.TextIOBase

Defines the base interface for character-oriented streams, including decoded text reads.

Version: Python 3.14; repository image, production runtime not attested

Syntax

io.TextIOBase()

Defines the base interface for character-oriented streams, including decoded text reads.

A text wrapper decodes underlying bytes. A read count describes characters, which can span multiple encoded bytes.

TextIOWrapper decodes bytes using its encoding and returns str. read(1) yields 'é', then 'x', then '' at EOF. A position returned by tell() may be an opaque cookie. Pass it back to seek() to restore the position instead of treating it as a character index. encoding identifies the encoding, errors the error handling and newlines the endings encountered in universal newline mode. TextIOWrapper.buffer exposes the binary stream. detach() returns it and makes the wrapper unusable. StringIO has no underlying binary buffer and detach() raises io.UnsupportedOperation.

import io
with io.TextIOWrapper(io.BytesIO('éx'.encode()),encoding='utf-8') as s:
    assert isinstance(s,io.TextIOBase) and s.read(1)=='é'
    cookie=s.tell()
    assert s.read(2)=='x' and s.read(1)==''
    assert s.seek(cookie)==cookie and s.read(1)=='x'
    try: s.write(b'x')
    except TypeError: pass
    else: raise AssertionError
raw=io.BytesIO(b'a\r\n')
s=io.TextIOWrapper(raw,encoding='utf-8',errors='strict',newline=None)
assert (s.encoding,s.errors,s.read(),s.newlines)==('utf-8','strict','a\n','\r\n')
assert s.buffer is s.detach() is raw
try: s.read()
except ValueError: pass
else: raise AssertionError
raw.close()
with io.StringIO() as s:
    try: s.detach()
    except io.UnsupportedOperation: pass
    else: raise AssertionError

Examples

import io
with io.TextIOWrapper(io.BytesIO("éx".encode()), encoding="utf-8") as stream:
    print(isinstance(stream, io.TextIOBase))
    print(stream.read(1), stream.read(1), repr(stream.read(1)))

Result

True
é x ''

TextIOWrapper decodes bytes using its encoding and returns str. read(1) yields 'é', then 'x', then '' at EOF. A position returned by tell() may be an opaque cookie. Pass it back to seek() to restore the position instead of treating it as a character index. encoding identifies the encoding, errors the error handling and newlines the endings encountered in universal newline mode. TextIOWrapper.buffer exposes the binary stream. detach() returns it and makes the wrapper unusable. StringIO has no underlying binary buffer and detach() raises io.UnsupportedOperation.

Sources