Repository navigation
Reword inheritance diagram for BufferedRandom to encompass _io and _pyio implementations #141627
Description
Documentation
The documentation for io.BufferedRandom states
A buffered binary stream providing higher-level access to a seekable RawIOBase raw binary stream. It inherits from BufferedReader and BufferedWriter.
(emphasis mine)
Except when runing cpython,
Python 3.14.0rc3 (main, Sep 18 2025, 19:47:22) [Clang 20.1.4 ] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> from io import BufferedRandom, BufferedReader
>>> issubclass(BufferedRandom, BufferedReader)
False
>>> BufferedRandom.mro()
[<class '_io.BufferedRandom'>, <class '_io._BufferedIOBase'>, <class '_io._IOBase'>, <class 'object'>]It seems that BufferedRandom does not inherit from either BufferedReader or BufferedWriter
Linked PRs
- gh-141627: Fix BufferedRandom inheritance documentation #141629
- [3.15] gh-141627: Fix BufferedRandom inheritance documentation (GH-141629) #150801
- [3.14] gh-141627: Fix BufferedRandom inheritance documentation (GH-141629) #150802
- [3.13] gh-141627: Fix BufferedRandom inheritance documentation (GH-141629) #150803
Activity
pythongh-141627: Fix BufferedRandom inheritance documentation
picnixz commentedon Nov 16, 2025
This is actually half-true. It does inherit from those classes when it's using the pure Python implementation. However, I see how confusing this can be and the alternative is to register the C implementation of
BufferedRandomas a virtual subclass ofBufferedReaderandBufferedWriterbut this is an overkill IMO.[-]Documentation states BufferedRandom inherits from BufferedReader and BufferedWriter, but it doesn't.[/-][+]Relax inheritance assumptions for `_io.BufferedRandom`[/+][-]Relax inheritance assumptions for `_io.BufferedRandom`[/-][+]Reword inheritance diagram for `BufferedRandom` to encompass `_io` and `_pyio` implementations[/+]cmaloney commentedon Nov 16, 2025
In the C case,
BufferedReader,BufferedWriter, andBufferedRandomall have the same corestruct buffered+ many method implementations. So it is implemented as though it inherited, just doesn't expose that at the Python abstraction.That it "behaves like" is already documented in the last paragraph of the
BufferedRandomclass documentation:I lean for just removing the "It inherits from" sentence entirely. It doesn't inherit but in my going through
topic-IOissues haven't seen any bugs filed against that until this one. Making it virtually inherit changesisinstancemight break some code; removing the doc line is unlikely to break anything.mohsinm-dev commentedon Nov 16, 2025
@cmaloney Thanks, that matches what I’m seeing too. In the C path, they do it effectively “as if” they inherited, but the Python MRO doesn’t expose that.
I’ll take the least‑surprising fix and drop the "It inherits from …” sentence entirely. The next paragraph already communicates the important part.
Merge branch 'main' into fix-bufferedrandom-docs-pythongh-141627
gh-141627: Fix BufferedRandom inheritance documentation (GH-141629)
[3.13] gh-141627: Fix BufferedRandom inheritance documentation (GH-14…
[3.14] gh-141627: Fix BufferedRandom inheritance documentation (GH-14…
[3.15] gh-141627: Fix BufferedRandom inheritance documentation (GH-14…