Update by Mark Russell -- clarify readinto(), and qualify tell()/seek() on

textio buffers.

pep-3116.txt

@@ -72,11 +72,11 @@ exactly one operating system call.
 
     ``.readinto(b: bytes) -> int``
 
-       Read up to ``n`` bytes from the object and stores them in
+       Read up to ``len(b)`` bytes from the object and stores them in
        ``b``, returning the number of bytes read.  Like .read, fewer
-       than ``n`` bytes may be read, and 0 indicates end of file.
+       than ``len(b)`` bytes may be read, and 0 indicates end of file.
        ``None`` is returned if a non-blocking object has no bytes
-       available.
+       available.  The length of ``b`` is never changed.
 
     ``.write(b: bytes) -> int``
 
@@ -100,7 +100,7 @@ Additionally, it defines a few other methods:
 
     ``.writable() -> bool``
 
-       Returns ``True`` if the object was opened write writing,
+       Returns ``True`` if the object was opened for writing,
        ``False`` otherwise.  If ``False``, ``.write()`` and
        ``.truncate()`` will raise an ``IOError`` if called.
 
@@ -277,15 +277,33 @@ per-character basis instead of a per-byte basis.  These methods are:
 
     ``.write(s: str) -> None``
 
+    ``.tell() -> object``
+
+        Return a cookie describing the current file position.
+        The only supported use for the cookie is with .seek()
+        with whence set to 0 (i.e. absolute seek).
+
+    ``.seek(pos: object, whence: int = 0) -> None``
+
+        Seek to position ``pos``.  If ``pos`` is non-zero, it must
+        be a cookie returned from ``.tell()`` and ``whence`` must be zero.
+
+    ``.truncate(pos: object = None) -> None``
+
+        Like ``BufferedIOBase.truncate()``, except that ``pos`` (if
+        not ``None``) must be a cookie previously returned by ``.tell()``.
+
+Unlike with raw I/O, the units for .seek() are not specified - some
+implementations (e.g. ``StringIO``) use characters and others
+(e.g. ``TextIOWrapper``) use bytes.  The special case for zero is to
+allow going to the start or end of a stream without a prior
+``.tell()``.  An implementation could include stream encoder state in
+the cookie returned from ``.tell()``.
+
+    
 ``TextIOBase`` implementations also provide several methods that are
 pass-throughs to the underlaying ``BufferedIOBase`` objects:
 
-    ``.seek(pos: int, whence: int = 0) -> None``
-
-    ``.tell() -> int``
-
-    ``.truncate(pos: int = None) -> None``
-
     ``.flush() -> None``
 
     ``.close() -> None``