diff options
author | Miss Islington (bot) <31488909+miss-islington@users.noreply.github.com> | 2019-09-14 20:47:31 (GMT) |
---|---|---|
committer | GitHub <noreply@github.com> | 2019-09-14 20:47:31 (GMT) |
commit | 4a71df88cdba77c409ee70146dd6445b19267df4 (patch) | |
tree | dee89011ae6ba99c4e62a25f8724b5f448acf9bd | |
parent | f37a9831027ecfe948697cdb5e35b417805d94e5 (diff) | |
download | cpython-4a71df88cdba77c409ee70146dd6445b19267df4.zip cpython-4a71df88cdba77c409ee70146dd6445b19267df4.tar.gz cpython-4a71df88cdba77c409ee70146dd6445b19267df4.tar.bz2 |
bpo-37635: Update arg name for seek() in IO tutorial (GH-16147)
Typically, the second positional argument for ``seek()`` is *whence*. That is the POSIX standard name (http://man7.org/linux/man-pages/man3/lseek.3p.html) and the name listed in the documentation for ``io`` module (https://docs.python.org/3/library/io.htmlGH-io.IOBase.seek).
The tutorial for IO is the only location where the second positional argument for ``seek()`` is referred to as *from_what*. I suspect this was created at an early point in Python's history, and was never updated (as this section predates the GitHub repository):
```
$ git grep "from_what"
Doc/tutorial/inputoutput.rst:To change the file object's position, use ``f.seek(offset, from_what)``. The position is computed
Doc/tutorial/inputoutput.rst:the *from_what* argument. A *from_what* value of 0 measures from the beginning
Doc/tutorial/inputoutput.rst:the reference point. *from_what* can be omitted and defaults to 0, using the
```
For consistency, I am suggesting that the tutorial be updated to use the same argument name as the IO documentation and POSIX standard for ``seek()``, particularly since this is the only location where *from_what* is being used.
Note: In the POSIX standard, *whence* is technically the third positional argument, but the first argument *fildes* (file descriptor) is implicit in Python.
https://bugs.python.org/issue37635
(cherry picked from commit ff603f6c3d3dc0e9ea8c1c51ce907c4821f42c54)
Co-authored-by: Kyle Stanley <aeros167@gmail.com>
-rw-r--r-- | Doc/tutorial/inputoutput.rst | 6 |
1 files changed, 3 insertions, 3 deletions
diff --git a/Doc/tutorial/inputoutput.rst b/Doc/tutorial/inputoutput.rst index 9fe1276..a404f4b 100644 --- a/Doc/tutorial/inputoutput.rst +++ b/Doc/tutorial/inputoutput.rst @@ -412,11 +412,11 @@ or a bytes object (in binary mode) -- before writing them:: represented as number of bytes from the beginning of the file when in binary mode and an opaque number when in text mode. -To change the file object's position, use ``f.seek(offset, from_what)``. The position is computed +To change the file object's position, use ``f.seek(offset, whence)``. The position is computed from adding *offset* to a reference point; the reference point is selected by -the *from_what* argument. A *from_what* value of 0 measures from the beginning +the *whence* argument. A *whence* value of 0 measures from the beginning of the file, 1 uses the current file position, and 2 uses the end of the file as -the reference point. *from_what* can be omitted and defaults to 0, using the +the reference point. *whence* can be omitted and defaults to 0, using the beginning of the file as the reference point. :: >>> f = open('workfile', 'rb+') |