Skip to main content

Lib/io.py

cpython 3.14 @ ab2d84fe1023/Lib/io.py

Lib/io.py is almost entirely a re-export file. The real implementation lives in Modules/_io/ (a C extension registered as _io). The pure-Python file exists so that import io works before the C extension is available (e.g., during interpreter bootstrap) and so that the module can provide a small number of pure-Python fallback definitions.

The file imports _io with from _io import * and then adds BlockingIOError (an alias for the built-in exception of the same name), DEFAULT_BUFFER_SIZE (8192), and open (re-exported from _io.open). The open_code function is also re-exported from _io and used when the interpreter runs in isolated mode (-I flag).

The abstract base class hierarchy (IOBase, RawIOBase, BufferedIOBase, TextIOBase) and the concrete class hierarchy (FileIO, BytesIO, StringIO, BufferedReader, BufferedWriter, BufferedRandom, BufferedRWPair, TextIOWrapper, IncrementalNewlineDecoder) are all defined in C and merely re-exported here. UnsupportedOperation is the exception raised by methods that are not supported on a given stream type.

Map​

LinesSymbolRolegopy
1-30Module docstring, _io import, __all__Imports the C extension and establishes the public namespace.module/io/module.go
31-60DEFAULT_BUFFER_SIZE, BlockingIOError, open, open_codeModule-level constants and the two entry-point functions; open is _io.open; BlockingIOError is the built-in.module/io/module.go
61-80Abstract base classes re-export: IOBase, RawIOBase, BufferedIOBase, TextIOBase, UnsupportedOperationThe four ABC layers and the sentinel exception; all implemented in C.module/io/module.go
81-100Concrete class re-export: FileIO, BytesIO, StringIO, BufferedReader, BufferedWriter, BufferedRandom, BufferedRWPair, TextIOWrapper, IncrementalNewlineDecoderAll nine concrete stream types; all implemented in C.module/io/module.go

Reading​

open dispatch logic (lines 31 to 60)​

cpython 3.14 @ ab2d84fe1023/Lib/io.py#L31-60 

DEFAULT_BUFFER_SIZE = 8 * 1024  # 8192

# Pretend this exception was created here.
BlockingIOError = BlockingIOError

open = _io.open
open_code = _io.open_code

_io.open is the canonical builtins.open. It parses the mode string, picks a concrete class, wraps a FileIO (raw) in a BufferedReader, BufferedWriter, or BufferedRandom, and optionally wraps that in a TextIOWrapper for text mode. open_code is the same entry point used by importlib and the -I isolated-mode flag; it may call a custom hook registered via PyFile_SetOpenCodeHook in the C API.

BlockingIOError is the built-in exception of the same name, re-bound here so that io.BlockingIOError and builtins.BlockingIOError are the identical object. DEFAULT_BUFFER_SIZE is 8192 bytes and is consulted by BufferedReader, BufferedWriter, and BufferedRandom when no explicit buffer size is given.

ABC hierarchy (lines 61 to 80)​

cpython 3.14 @ ab2d84fe1023/Lib/io.py#L61-80 

# ABCs
from _io import (IOBase, RawIOBase, BufferedIOBase, TextIOBase,
                 UnsupportedOperation)

The four abstract layers form a simple hierarchy:

IOBase
├── RawIOBase        # unbuffered binary: read/readinto/write
├── BufferedIOBase   # buffered binary: read/read1/readinto/write/detach
└── TextIOBase       # text: read/readline/write/seek/tell/detach

IOBase provides fileno, seek, tell, truncate, flush, close, readable, writable, seekable, __iter__, and readline. Subclasses override only the methods they support; all others raise UnsupportedOperation (a subclass of both OSError and ValueError so that code catching either will intercept it).

BytesIO and StringIO in-memory streams (lines 81 to 100)​

cpython 3.14 @ ab2d84fe1023/Lib/io.py#L81-100 

from _io import (FileIO,
                 BytesIO, StringIO,
                 BufferedReader, BufferedWriter,
                 BufferedRandom, BufferedRWPair,
                 TextIOWrapper,
                 IncrementalNewlineDecoder)

BytesIO is a BufferedIOBase backed by a resizable bytes buffer in memory. It supports read, write, seek, tell, getvalue, and getbuffer. StringIO is the text equivalent: a TextIOBase backed by a str buffer. Both accept an optional initial value in their constructor and reset the position to 0. Neither supports fileno(); calling it raises UnsupportedOperation.

TextIOWrapper is the most complex concrete class: it wraps a BufferedIOBase, handles a configurable encoding and errors policy, translates newlines via IncrementalNewlineDecoder when newline is not None, and manages a write-through or write-through-plus-buffer mode via the line_buffering and write_through flags.