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.