classification
Title: Document '/' in signatures
Type: enhancement Stage: commit review
Components: Argument Clinic, Documentation Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: larry Nosy List: benjamin.peterson, berker.peksag, cheryl.sabella, docs@python, emily.zhao, josh.r, jwilk, larry, lys.nikolaou, ncoghlan, noah.haasis, pablogsal, pradyunsg, rhettinger, terry.reedy, veky, zach.ware
Priority: normal Keywords: easy, patch, patch, patch

Created on 2014-04-20 10:07 by veky, last changed 2019-05-31 09:27 by terry.reedy.

Pull Requests
URL Status Linked Edit
PR 10641 merged lys.nikolaou, 2018-11-21 22:06
PR 10641 merged lys.nikolaou, 2018-11-21 22:06
PR 10641 merged lys.nikolaou, 2018-11-21 22:06
PR 12266 merged miss-islington, 2019-03-10 11:30
Messages (21)
msg216899 - (view) Author: Vedran Čačić (veky) * Date: 2014-04-20 10:07
Please look at the output of help(object.__ge__).

1. What's that $ in front of self? lt and gt don't have it.

2. What's that / as a third argument? Many wrapper functions have it (for example, see help(tuple.__len__).

3. What's that -- as the first line of doc? Similar methods don't have it.
msg216900 - (view) Author: Josh Rosenberg (josh.r) * (Python triager) Date: 2014-04-20 12:47
I don't know about the other bits, but that trailing '/' is how Argument Clinic (which makes full featured inspection available to built-in functions) notes that the parameters are positional only, and cannot be passed by keyword. See PEP436.
msg216901 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2014-04-20 12:49
1) This was due to a typo. The release of Python 3.4 saw the introduction of new introspection information on many C-implemented functions thanks to Argument Clinic (see PEP 436, I think it is). As part of that (still ongoing) transition, the default doctrings for type slots like __ge__ were given Argument Clinic-style signatures, and __ge__ had a typo.

I fixed that typo on Friday (actually prompted by your previous issue about len's bad signature).

2) That marker now shows that all proceeding arguments are positional-only.  We should probably make sure that is well documented somewhere, possibly in the tutorial.

3) This was also due to the typo I fixed.
msg219979 - (view) Author: Emily Zhao (emily.zhao) * Date: 2014-06-07 21:24
Can someone close this? I think it's fixed.
msg219983 - (view) Author: Benjamin Peterson (benjamin.peterson) * (Python committer) Date: 2014-06-07 21:44
The original bug (junk in various doc strings) has been fixed, but I think the positional argument "/" syntax still needs docs. It's a little tricky because "/" is not actually valid syntax; it's just for documentation signatures.
msg219987 - (view) Author: Emily Zhao (emily.zhao) * Date: 2014-06-07 22:09
where's the best place for that documentation to live?
msg223893 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2014-07-24 20:41
Apologies for the delay in answering, Emily.  And, unfortunately, I don't have a good answer.  If you would like to write a patch, I would suggest just sticking the documentation wherever you think is best and make sure there is a link to it from the Symbols index page.  Whoever commits your patch will either agree with your placement or have a better idea of where to put it, and will either move it themselves or work with you to move it.

Here are a few possible places it could go, off the top of my head and without really looking:
- in the pydoc docs
- in the help() builtin docs
- in or near the inspect.Signature docs
- in the Clinic HOWTO
- somewhere in the tutorial (though I'm not sure where would be good)
msg323436 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2018-08-12 09:00
I'd suggest adding a FAQ entry to the "Core Language" section at https://docs.python.org/3/faq/programming.html#core-language then we can link to it from the places (except pydoc docs) Zachary listed in msg223893.
msg324982 - (view) Author: Noah Haasis (noah.haasis) * Date: 2018-09-11 04:40
Can I work on this?
msg325005 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2018-09-11 13:39
Welcome, Noah! Feel free to work on this issue, but please note that there is no consensus on the best place to document / signatures, so you may need to move your changes between locations (e.g. from Doc/faq/programming.rst to Doc/gloassary.rst) before we merge your work.
msg328982 - (view) Author: Pradyun Gedam (pradyunsg) * Date: 2018-10-31 11:08
We now have a PEP for this; just noting this here since I don't see a cross reference between them.

https://www.python.org/dev/peps/pep-0570/
msg330193 - (view) Author: Lysandros Nikolaou (lys.nikolaou) * Date: 2018-11-21 11:55
Noah, are you working on this?
msg330209 - (view) Author: Noah Haasis (noah.haasis) * Date: 2018-11-21 16:53
I don‘t have the time right now. Feel free to work on it!
msg337017 - (view) Author: Lysandros Nikolaou (lys.nikolaou) * Date: 2019-03-02 18:43
Ping for review.
msg337611 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2019-03-10 11:30
New changeset 1aeeaeb79efa4de41f97b58547e23c2965ecabc5 by Nick Coghlan (Lysandros Nikolaou) in branch 'master':
bpo-21314: Add a FAQ entry about positional only parameters (GH-10641)
https://github.com/python/cpython/commit/1aeeaeb79efa4de41f97b58547e23c2965ecabc5
msg337612 - (view) Author: miss-islington (miss-islington) Date: 2019-03-10 11:36
New changeset 87f5255cdc9aa737d445b5813e52c41e5266a862 by Miss Islington (bot) in branch '3.7':
bpo-21314: Add a FAQ entry about positional only parameters (GH-10641)
https://github.com/python/cpython/commit/87f5255cdc9aa737d445b5813e52c41e5266a862
msg337613 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2019-03-10 11:46
I went ahead and merged Lysandros's new FAQ entry (Thank you Lysandros!), as having some level of documentation for this notation is markedly better than the previous "none at all", and the PR added cross-references from the builtins and inspect module docs in addition to adding the FAQ itself.

However, I'm not closing the issue yet as:

- the exact wording could likely stand to be tweaked a bit (in particular, I'm not sure it's a good idea to reference PEP 570 from the FAQ entry)

- we may want to enhance pydoc itself to explain the notation inline (e.g. by appending a footer saying "Note: parameters to the left of ``/`` entries are positional only and cannot be passed by name" after the docstring being displayed when positional only parameters are found, and "Note: parameters to the right of ``*`` and ``*name`` entries are keyword only and can only be passed by name" when keyword only parameters are found)

- we may want to file a follow-up issue proposing that `pydoc` go back to either not marking positional-only parameters at all, or marking them differently (e.g. with "Note: *x*, *y*, and *z* are positional only parameters that cannot be passed by name" after the individual callable docstrings)
msg337708 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-03-11 22:54
There are a few other open issues about positional-only keywords (for example, #10789 and #8350).  I wasn't sure what, if anything, could be done with those now that the '/' is available and documented.
msg337881 - (view) Author: Lysandros Nikolaou (lys.nikolaou) * Date: 2019-03-13 22:17
I agree with Nick, that pydoc should somehow be updated to mark positional-only parameters as such. I believe that the third approach proposed by Nick is the most sensible one, as it makes the life of new developers easier by explicitly listing all the positional-only parameters. I could open a new issue and work on a PR, if you all agree that that is the way to go.
msg343595 - (view) Author: Pablo Galindo Salgado (pablogsal) * (Python committer) Date: 2019-05-27 01:34
I think we can revisit this now that PEP570 is accepted
msg344047 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-05-31 09:27
Hooray!  Now that PEP570 is implemented in 3.8:

>>> def f(a, /, *, b): return 3
...
>>> f(0, b=2)
3
# other combinations raise

and somewhat documented, ('/' in grammar of '8.6 Function definitions', though not explained, should its status become final and listing moved?
History
Date User Action Args
2019-05-31 09:27:15terry.reedysetkeywords: patch, patch, patch, easy
nosy: + terry.reedy
messages: + msg344047

2019-05-27 01:34:54pablogsalsetkeywords: patch, patch, patch, easy
nosy: + pablogsal
messages: + msg343595

2019-03-13 22:17:14lys.nikolaousetmessages: + msg337881
2019-03-11 22:54:54cheryl.sabellasetkeywords: patch, patch, patch, easy
nosy: + cheryl.sabella
messages: + msg337708

2019-03-10 11:46:02ncoghlansetkeywords: patch, patch, patch, easy
messages: + msg337613
nosy: + rhettinger, - miss-islington
stage: patch review -> commit review
2019-03-10 11:36:20miss-islingtonsetnosy: + miss-islington
messages: + msg337612
2019-03-10 11:30:24miss-islingtonsetpull_requests: + pull_request12250
2019-03-10 11:30:15ncoghlansetnosy: + ncoghlan
messages: + msg337611
2019-03-02 18:43:58lys.nikolaousetmessages: + msg337017
2018-11-21 22:11:21yselivanovsetkeywords: patch, patch, patch, easy
nosy: - yselivanov
2018-11-21 22:06:55lys.nikolaousetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request9893
2018-11-21 22:06:46lys.nikolaousetkeywords: + patch
stage: needs patch -> needs patch
pull_requests: + pull_request9892
2018-11-21 22:06:35lys.nikolaousetkeywords: + patch
stage: needs patch -> needs patch
pull_requests: + pull_request9891
2018-11-21 16:53:23noah.haasissetmessages: + msg330209
2018-11-21 11:55:03lys.nikolaousetnosy: + lys.nikolaou
messages: + msg330193
2018-10-31 11:08:44pradyunsgsetnosy: + pradyunsg
messages: + msg328982
2018-09-11 13:39:51berker.peksagsetmessages: + msg325005
versions: + Python 3.6, Python 3.7, Python 3.8, - Python 3.4, Python 3.5
2018-09-11 04:40:11noah.haasissetnosy: + noah.haasis
messages: + msg324982
2018-08-12 09:00:30berker.peksagsetnosy: + berker.peksag
messages: + msg323436
2018-04-20 17:08:03jwilksetnosy: + jwilk
2018-04-17 20:52:04martin.panterlinkissue33300 superseder
2015-02-25 15:32:44serhiy.storchakasetcomponents: + Argument Clinic
2014-07-24 20:41:48zach.waresetmessages: + msg223893
2014-06-07 22:09:30emily.zhaosetmessages: + msg219987
2014-06-07 21:44:59benjamin.petersonsetnosy: + benjamin.peterson
messages: + msg219983
2014-06-07 21:24:11emily.zhaosetnosy: + emily.zhao
messages: + msg219979
2014-04-29 15:31:11zach.waresetkeywords: + easy
status: open
stage: needs patch
type: enhancement
versions: + Python 3.5
2014-04-25 22:22:28terry.reedysetstatus: open -> (no value)
title: Bizarre help -> Document '/' in signatures
2014-04-21 05:17:44yselivanovsetnosy: + yselivanov
2014-04-20 12:49:30zach.waresetnosy: + zach.ware
messages: + msg216901
2014-04-20 12:47:07josh.rsetnosy: + josh.r
messages: + msg216900
2014-04-20 11:29:20georg.brandlsetassignee: docs@python -> larry

nosy: + larry
2014-04-20 10:07:19vekycreate