Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

bpo-37635: Update arg name for seek() in IO tutorial #16147

Merged
merged 1 commit into from Sep 14, 2019

Conversation

aeros
Copy link
Member

@aeros aeros commented Sep 14, 2019

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.html#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

Automerge-Triggered-By: @pitrou

@aeros
Copy link
Member Author

aeros commented Sep 14, 2019

/cc @pitrou

pitrou
pitrou approved these changes Sep 14, 2019
Copy link
Member

@pitrou pitrou left a comment

+1, this looks like a good idea.

@pitrou pitrou added the 🤖 automerge PR will be merged once it's been approved and all CI passed label Sep 14, 2019
@miss-islington miss-islington merged commit ff603f6 into python:master Sep 14, 2019
@miss-islington
Copy link
Contributor

miss-islington commented Sep 14, 2019

Thanks @aeros167 for the PR 🌮🎉.. I'm working now to backport this PR to: 3.7, 3.8.
🐍🍒🤖

@bedevere-bot
Copy link

bedevere-bot commented Sep 14, 2019

GH-16150 is a backport of this pull request to the 3.8 branch.

@bedevere-bot
Copy link

bedevere-bot commented Sep 14, 2019

GH-16151 is a backport of this pull request to the 3.7 branch.

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Sep 14, 2019
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 ff603f6)

Co-authored-by: Kyle Stanley <aeros167@gmail.com>
miss-islington added a commit that referenced this pull request Sep 14, 2019
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 ff603f6)

Co-authored-by: Kyle Stanley <aeros167@gmail.com>
miss-islington added a commit that referenced this pull request Sep 14, 2019
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 ff603f6)

Co-authored-by: Kyle Stanley <aeros167@gmail.com>
@aeros
Copy link
Member Author

aeros commented Sep 14, 2019

Thanks Antoine!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir 🤖 automerge PR will be merged once it's been approved and all CI passed skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

5 participants