Repository navigation
Clarify documentation of positional-only default values #67926
Description
| BPO | 23738 |
|---|---|
| Nosy | @birkenfeld, @ezio-melotti, @bitdancer, @berkerpeksag, @vadmium, @serhiy-storchaka |
| Dependencies | |
| Files |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
assignee = None
closed_at = None
created_at = <Date 2015-03-22.10:31:01.273>
labels = ['type-feature', 'docs']
title = 'Clarify documentation of positional-only default values'
updated_at = <Date 2020-05-22.18:24:08.773>
user = 'https://github.com/vadmium'bugs.python.org fields:
activity = <Date 2020-05-22.18:24:08.773>
actor = 'brett.cannon'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2015-03-22.10:31:01.273>
creator = 'martin.panter'
dependencies = ['14586', '25030', '25810']
files = ['38632', '38800', '40417', '41253']
hgrepos = []
issue_num = 23738
keywords = ['patch']
message_count = 12.0
messages = ['238890', '238893', '238894', '238922', '239025', '239129', '239869', '241591', '250277', '250278', '255997', '257229']
nosy_count = 8.0
nosy_names = ['georg.brandl', 'ezio.melotti', 'r.david.murray', 'docs@python', 'python-dev', 'berker.peksag', 'martin.panter', 'serhiy.storchaka']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue23738'
versions = ['Python 3.4', 'Python 3.5', 'Python 3.6']
Activity
vadmium commentedon Mar 22, 2015
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
to
References:
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):
vadmium commentedon Mar 22, 2015
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?
serhiy-storchaka commentedon Mar 22, 2015
./python Tools/clinic/clinic.py --make
or just
bitdancer commentedon Mar 22, 2015
Personally I would rather stick to the [] syntax in the docs, with the default values mentioned in the text.
brettcannon commentedon Mar 23, 2015
I say switch to what Argument Clinic uses, else there's a disconnect syntactically between help() and the docs.
bitdancer commentedon Mar 24, 2015
That's a good point.
vadmium commentedon Apr 2, 2015
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.
vadmium commentedon Apr 20, 2015
Of course in a new release, the functions could actually grow support for keywords, sidestepping the problem. bpo-8706 proposes to do this.
And see bpo-13386 about the conventions for optional arguments more generally.
python-dev commentedon Sep 9, 2015
New changeset fdb5d84f9948 by Martin Panter <vadmium> in branch '3.4':
Issue bpo-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 bpo-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 bpo-23738: Merge 3.5 into 3.6
https://hg.python.org/cpython/rev/6177482ce6a1
vadmium commentedon Sep 9, 2015
I have committed the obvious keyword argument name fixes from my patch. Now patch v3 contains just the PEP-457 changes to be considered.
vadmium commentedon Dec 6, 2015
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: bpo-23214.
ezio-melotti commentedon Dec 30, 2015
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).
StanFromIreland commentedon Aug 14, 2025
I believe that this is a duplicate of the recent issue: #131885
vadmium commentedon Aug 15, 2025
Looks like it. The main change left from my patches is the FileIO parameter name fix and test in https://bugs.python.org/file41253/square-brackets.patch.
All of my v3 patch is now redundant, and the other signatures identified in square-brackets.patch have adopted the slash notation:
StanFromIreland commentedon Aug 15, 2025
Do you wish to apply the patch?
*and/as needed #131885