classification
Title: Document '/' in signatures
Type: enhancement Stage: patch 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, docs@python, emily.zhao, josh.r, jwilk, larry, lys.nikolaou, noah.haasis, pradyunsg, veky, zach.ware
Priority: normal Keywords: easy, patch, patch, patch

Created on 2014-04-20 10:07 by veky, last changed 2018-11-21 22:11 by yselivanov.

Pull Requests
URL Status Linked Edit
PR 10641 open lys.nikolaou, 2018-11-21 22:06
PR 10641 open lys.nikolaou, 2018-11-21 22:06
PR 10641 open lys.nikolaou, 2018-11-21 22:06
Messages (13)
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!
History
Date User Action Args
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