diff --git a/Doc/library/io.rst b/Doc/library/io.rst --- a/Doc/library/io.rst +++ b/Doc/library/io.rst @@ -159,6 +159,21 @@ example, :class:`BufferedIOBase` provides unoptimized implementations of :meth:`~IOBase.readinto` and :meth:`~IOBase.readline`. + .. note:: + + In the rest of this section, the interfaces provided by the ABCs + are documented as if they were regular classes. However, it + should be kept in mind that ABCs cannot be instantiated + directly, and that the documentation of an ABC's method thus + does not describe how the method is implemented in the ABC, but + how derived classes are *expected* to implement it. For example, + the documentation for :meth:`IOBase.close` specifies that "This + method has no effect if the file is already closed", but should + be understood as "any class claiming to be compatible with + :class:`IOBase` must ensure that its ``close`` method may be + called multiple times and that it will do nothing if the + instance is already closed". + At the top of the I/O hierarchy is the abstract base class :class:`IOBase`. It defines the basic interface to a stream. Note, however, that there is no separation between reading and writing to streams; implementations are allowed