docs/library/io: Add documentation for the io.IOBase class.

Document the three methods that IOBase subclasses implement (readinto,
write, ioctl) and the common ioctl operations. Includes a simple write-only
stream example and a pollable ring buffer example.

IOBase docs are inline in io.rst before StringIO/BytesIO, following
CPython's structure.

Also fix a statement in io.rst that incorrectly claimed streams cannot be
subclassed in pure Python.

Signed-off-by: Andrew Leech <andrew.leech@planet-innovation.com>

Author: pi-anl

docs/library/io.rst

@@ -71,8 +71,9 @@ buffered, they aren't in MicroPython. (Indeed, that's one of the cases
 for which we may introduce buffering support.)
 
 Note that for efficiency, MicroPython doesn't provide abstract base
-classes corresponding to the hierarchy above, and it's not possible
-to implement, or subclass, a stream class in pure Python.
+classes corresponding to the hierarchy above.  However, the
+:class:`IOBase` class can be subclassed to implement custom stream
+objects in pure Python.
 
 Functions
 ---------
@@ -86,6 +87,69 @@ Functions
 Classes
 -------
 
+.. class:: IOBase()
+
+   Base class for implementing custom stream objects in Python. Subclasses
+   can override ``readinto``, ``write``, and ``ioctl`` to create objects
+   that work with ``print()``, ``json.dump()``, ``select.poll()``,
+   ``open()`` via a user filesystem, and other stream consumers.
+
+   .. admonition:: Difference to CPython
+      :class: attention
+
+      In CPython, ``io.IOBase`` has a much larger API surface. MicroPython's
+      ``IOBase`` is minimal: the C stream infrastructure provides standard
+      methods like ``read()``, ``readline()``, ``seek()``, ``close()``, and
+      ``flush()`` automatically. Subclasses only need to implement the
+      methods below.
+
+   Subclasses implement some or all of the following methods. The C stream
+   layer calls these internally when user code calls standard stream
+   functions.
+
+   .. method:: IOBase.readinto(buf)
+
+      Read data into *buf* (a ``bytearray`` sized by the caller). Return the
+      number of bytes read, 0 at EOF, or ``None`` if no data is available on
+      a non-blocking stream. Return a negative errno value (e.g. ``-errno.EIO``
+      or ``-1``) to signal an error.
+
+   .. method:: IOBase.write(buf)
+
+      Write *buf* (a ``bytearray``) to the stream. Return the number of
+      bytes written, or ``None`` if a non-blocking stream cannot accept data.
+      Return a negative errno value to signal an error.
+
+   .. method:: IOBase.ioctl(op, arg)
+
+      Control the stream and query its properties. The operation to perform
+      is given by *op* which is one of the following integers:
+
+        - 1 -- flush write buffers (*arg* is unused)
+        - 3 -- poll for readiness; *arg* is a bitmask of events to check,
+          return a bitmask of ready events. Poll flags:
+
+          * ``0x0001`` -- data available for reading
+          * ``0x0004`` -- stream ready for writing
+          * ``0x0008`` -- error condition
+          * ``0x0010`` -- hang up (e.g. connection closed)
+          * ``0x0020`` -- invalid request
+
+        - 4 -- close the stream (*arg* is unused)
+        - 11 -- return the preferred read buffer size, or 0 (*arg* is unused)
+
+      As a minimum ``ioctl(4, ...)`` should be handled to support stream
+      closure. Implement ``ioctl(3, ...)`` if the stream will be used with
+      ``select.poll()`` or ``asyncio``.
+
+      Other operations exist for advanced use cases (2 = seek, 5 = timeout,
+      10 = fileno); see ``py/stream.h`` for the full list.
+
+      Must always return an integer. Return 0 for success, or ``-1`` for
+      unsupported operations. (Returning 0 for an unhandled operation tells
+      the C layer the operation was processed successfully, which may cause
+      incorrect behaviour.)
+
 .. class:: StringIO([string])
 .. class:: BytesIO([string])
 
@@ -119,3 +183,77 @@ Classes
         :class: attention
 
         These constructors are a MicroPython extension.
+
+IOBase Examples
+---------------
+
+A minimal write-only stream that collects output into a buffer::
+
+    import io
+
+    class MyOutput(io.IOBase):
+        def __init__(self):
+            self.data = bytearray()
+
+        def write(self, buf):
+            self.data.extend(buf)
+            return len(buf)
+
+        def ioctl(self, op, arg):
+            if op == 4:  # close
+                return 0
+            return -1
+
+    s = MyOutput()
+    print("hello", file=s)
+    print(s.data)  # bytearray(b'hello\n')
+
+A readable stream that can be used with ``select.poll()``::
+
+    import io, select
+    from micropython import const
+
+    _MP_STREAM_POLL = const(3)
+    _MP_STREAM_POLL_RD = const(0x0001)
+    _MP_STREAM_CLOSE = const(4)
+
+    class RingBuffer(io.IOBase):
+        def __init__(self, size):
+            self._buf = bytearray(size)
+            self._size = size
+            self._wpos = 0
+            self._rpos = 0
+
+        def _available(self):
+            return (self._wpos - self._rpos) % self._size
+
+        def put(self, data):
+            for b in data:
+                self._buf[self._wpos % self._size] = b
+                self._wpos = (self._wpos + 1) % self._size
+
+        def readinto(self, buf):
+            n = min(len(buf), self._available())
+            for i in range(n):
+                buf[i] = self._buf[self._rpos % self._size]
+                self._rpos = (self._rpos + 1) % self._size
+            return n
+
+        def ioctl(self, op, arg):
+            if op == _MP_STREAM_POLL:
+                if arg & _MP_STREAM_POLL_RD and self._available() > 0:
+                    return _MP_STREAM_POLL_RD
+                return 0
+            if op == _MP_STREAM_CLOSE:
+                return 0
+            return -1
+
+    rb = RingBuffer(64)
+    rb.put(b"test data")
+
+    poller = select.poll()
+    poller.register(rb, select.POLLIN)
+    for obj, flags in poller.poll(0):
+        buf = bytearray(16)
+        n = obj.readinto(buf)
+        print(buf[:n])  # bytearray(b'test data')