classification
Title: Clarify documentation of positional-only default values
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.6, Python 3.4, Python 3.5
process
Status: open Resolution:
Dependencies: 14586 25030 25810 Superseder:
Assigned To: docs@python Nosy List: berker.peksag, brett.cannon, docs@python, ezio.melotti, georg.brandl, martin.panter, python-dev, r.david.murray, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2015-03-22 10:31 by martin.panter, last changed 2015-12-30 05:55 by ezio.melotti.

Files
File name Uploaded Description Edit
pos-defaults.patch martin.panter, 2015-03-22 10:31 review
pos-defaults.v2.patch martin.panter, 2015-04-02 01:32 review
pos-defaults.v3.patch martin.panter, 2015-09-09 03:54 review
square-brackets.patch martin.panter, 2015-12-06 01:25 review
Messages (12)
msg238890 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-03-22 10:31
This patch adds the PEP 457 positional-only slash “/” indicator to some function signatures in the documentation. I only looked at the the os, builtin, binascii, zlib and fcntl modules, and their functions where the documentation incorrectly suggests that they accept keyword arguments. For example, I changed

eval(expression, globals=None, locals=None)

to

eval(expression, globals=None, locals=None, /)

References:

* Issue 22832: “fcntl” module changed to look like accepting keyword arguments
* Ongoing discussion: <https://mail.python.org/pipermail/python-dev/2015-March/138847.html>

There are many more instances where square brackets are used, or the arguments are mandatory. See the PEP for examples, but I do not think it is so important to “fix” them.

I also fixed parameter name mismatches that I discovered for a quite a few functions that do take keyword arguments.

One more thing I noticed, that I do not know how to fix, is the Argument Clinic signatures list invalid default values for zlib.compressobj(zdict=None) and os.utime(ns=None):

>>> zlib.compressobj(zdict=None)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: 'NoneType' does not support the buffer interface
>>> os.utime("dummy", ns=None)
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
TypeError: utime: 'ns' must be a tuple of two ints
msg238893 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-03-22 10:53
Hmm it seems my change for os.utimes() in Modules/posixmodule.c does not automatically get reflected in the doc string. Is there some script I can run to regenerate it, or do I have to do it manually?
msg238894 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2015-03-22 11:22
./python Tools/clinic/clinic.py --make

or just

    make clinic
msg238922 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-03-22 17:18
Personally I would rather stick to the [] syntax in the docs, with the default values mentioned in the text.
msg239025 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2015-03-23 14:08
I say switch to what Argument Clinic uses, else there's a disconnect syntactically between help() and the docs.
msg239129 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-03-24 14:35
That's a good point.
msg239869 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-04-02 01:32
pos-defaults.v2.patch includes the results of “make clinic” to fix the doc strings.

Is there a consensus to use PEP 457’s slash “/” notation? At one point I think I saw Serhiy was concerned that it might be confusing.
msg241591 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-04-20 02:30
Of course in a new release, the functions could actually grow support for keywords, sidestepping the problem. Issue 8706 proposes to do this.

And see Issue 13386 about the conventions for optional arguments more generally.
msg250277 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2015-09-09 03:56
New changeset fdb5d84f9948 by Martin Panter <vadmium> in branch '3.4':
Issue #23738: Document and test actual keyword parameter names
https://hg.python.org/cpython/rev/fdb5d84f9948

New changeset 40bf1ca3f715 by Martin Panter <vadmium> in branch '3.5':
Issue #23738: Merge 3.4 into 3.5
https://hg.python.org/cpython/rev/40bf1ca3f715

New changeset 6177482ce6a1 by Martin Panter <vadmium> in branch 'default':
Issue #23738: Merge 3.5 into 3.6
https://hg.python.org/cpython/rev/6177482ce6a1
msg250278 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-09-09 03:58
I have committed the obvious keyword argument name fixes from my patch. Now patch v3 contains just the PEP 457 changes to be considered.
msg255997 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-12-06 01:25
Here is a more conservative patch using square brackets, and documenting the defaults in the text. I updated all the documentation from my previous patch, and added new changes for the “io” module.

One quirk was that BufferedReader.read1() does not actually support the value −1. Therefore I changed the base class to BufferedIOBase.read1([size]) without mentioning what happens when size is omitted. Related: Issue 23214.
msg257229 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2015-12-30 05:55
One thought that occurred to me is that we could make the * and / in the signature links that point to a relevant section of the documentation.
I believe this is doable with Sphinx, even though I'm not sure how complex it is and if it's worth it.  If we do this, people will be able to find out easily what they mean (especially considering that it's hard to search for them).
History
Date User Action Args
2015-12-30 05:55:41ezio.melottisetmessages: + msg257229
2015-12-06 01:25:38martin.pantersetfiles: + square-brackets.patch

messages: + msg255997
2015-12-05 23:27:17martin.pantersetdependencies: + Python 3 documentation for eval is incorrect
2015-09-20 05:13:28martin.pantersetdependencies: + TypeError: truncate() takes no keyword arguments
2015-09-09 03:58:50martin.pantersetmessages: + msg250278
2015-09-09 03:56:01python-devsetnosy: + python-dev
messages: + msg250277
2015-09-09 03:54:44martin.pantersetfiles: + pos-defaults.v3.patch
nosy: + berker.peksag

versions: + Python 3.6
2015-09-08 22:21:43martin.pantersetdependencies: + io.[Text]IOBase.seek doesn't take keyword parameter
2015-04-20 02:30:04martin.pantersetmessages: + msg241591
2015-04-02 01:32:51martin.pantersetfiles: + pos-defaults.v2.patch

messages: + msg239869
2015-03-24 14:35:29r.david.murraysetmessages: + msg239129
2015-03-23 14:08:37brett.cannonsetmessages: + msg239025
2015-03-22 17:18:33r.david.murraysetnosy: + r.david.murray, georg.brandl
messages: + msg238922
2015-03-22 14:42:05brett.cannonsetnosy: + brett.cannon
2015-03-22 11:25:09ezio.melottisetnosy: + ezio.melotti

type: enhancement
stage: patch review
2015-03-22 11:22:47serhiy.storchakasetmessages: + msg238894
2015-03-22 10:53:19martin.pantersetmessages: + msg238893
2015-03-22 10:31:01martin.pantercreate