[Python-checkins] r54696 - peps/trunk/pep-3116.txt

[guido.van.rossum]

Author: guido.van.rossum
Date: Thu Apr  5 20:25:11 2007
New Revision: 54696

Modified:
   peps/trunk/pep-3116.txt
Log:
Update by Mark Russell -- clarify readinto(), and qualify tell()/seek() on 
textio buffers.


Modified: peps/trunk/pep-3116.txt
==============================================================================
--- peps/trunk/pep-3116.txt	(original)
+++ peps/trunk/pep-3116.txt	Thu Apr  5 20:25:11 2007
@@ -72,11 +72,11 @@
 
     ``.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 @@
 
     ``.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,14 +277,32 @@
 
     ``.write(s: str) -> None``
 
-``TextIOBase`` implementations also provide several methods that are
-pass-throughs to the underlaying ``BufferedIOBase`` objects:
+    ``.tell() -> object``
 
-    ``.seek(pos: int, whence: int = 0) -> None``
+        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).
 
-    ``.tell() -> int``
+    ``.seek(pos: object, whence: int = 0) -> None``
 
-    ``.truncate(pos: int = None) -> 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:
 
     ``.flush() -> None``