Repository navigation
Document '/' in signatures #65513
Description
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 = 'https://github.com/larryhastings'
closed_at = <Date 2022-04-04.20:43:41.240>
created_at = <Date 2014-04-20.10:07:19.415>
labels = ['easy', '3.7', '3.8', 'type-feature', 'expert-argument-clinic', 'docs']
title = "Document '/' in signatures"
updated_at = <Date 2022-04-04.20:43:41.236>
user = 'https://github.com/vedgar'bugs.python.org fields:
activity = <Date 2022-04-04.20:43:41.236>
actor = 'petr.viktorin'
assignee = 'larry'
closed = True
closed_date = <Date 2022-04-04.20:43:41.240>
closer = 'petr.viktorin'
components = ['Documentation', 'Argument Clinic']
creation = <Date 2014-04-20.10:07:19.415>
creator = 'veky'
dependencies = []
files = []
hgrepos = []
issue_num = 21314
keywords = ['patch', 'patch', 'patch', 'easy']
message_count = 22.0
messages = ['216899', '216900', '216901', '219979', '219983', '219987', '223893', '323436', '324982', '325005', '328982', '330193', '330209', '337017', '337611', '337612', '337613', '337708', '337881', '343595', '344047', '416695']
nosy_count = 18.0
nosy_names = ['rhettinger', 'terry.reedy', 'ncoghlan', 'larry', 'benjamin.peterson', 'jwilk', 'petr.viktorin', 'docs@python', 'berker.peksag', 'zach.ware', 'pradyunsg', 'josh.r', 'veky', 'emily.zhao', 'cheryl.sabella', 'lys.nikolaou', 'pablogsal', 'noah.haasis']
pr_nums = ['10641', '10641', '10641', '12266']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue21314'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']
Activity
vedgar commentedon Apr 20, 2014
Please look at the output of help(object.__ge__).
What's that $ in front of self? lt and gt don't have it.
What's that / as a third argument? Many wrapper functions have it (for example, see help(tuple.__len__).
What's that -- as the first line of doc? Similar methods don't have it.
MojoVampire commentedon Apr 20, 2014
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 PEP-436.
zware commentedon Apr 20, 2014
I fixed that typo on Friday (actually prompted by your previous issue about len's bad signature).
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.
This was also due to the typo I fixed.
[-]Bizarre help[/-][+]Document '/' in signatures[/+]emilyzhao commentedon Jun 7, 2014
Can someone close this? I think it's fixed.
benjaminp commentedon Jun 7, 2014
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.
emilyzhao commentedon Jun 7, 2014
where's the best place for that documentation to live?
zware commentedon Jul 24, 2014
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:
4 remaining items
pradyunsg commentedon Oct 31, 2018
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/
lysnikolaou commentedon Nov 21, 2018
Noah, are you working on this?
noahhaasis commentedon Nov 21, 2018
I don‘t have the time right now. Feel free to work on it!
lysnikolaou commentedon Mar 2, 2019
Ping for review.
ncoghlan commentedon Mar 10, 2019
New changeset 1aeeaeb by Nick Coghlan (Lysandros Nikolaou) in branch 'master':
bpo-21314: Add a FAQ entry about positional only parameters (GH-10641)
1aeeaeb
miss-islington commentedon Mar 10, 2019
New changeset 87f5255 by Miss Islington (bot) in branch '3.7':
bpo-21314: Add a FAQ entry about positional only parameters (GH-10641)
87f5255
ncoghlan commentedon Mar 10, 2019
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*nameentries 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
pydocgo 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)csabella commentedon Mar 11, 2019
There are a few other open issues about positional-only keywords (for example, bpo-10789 and bpo-8350). I wasn't sure what, if anything, could be done with those now that the '/' is available and documented.
lysnikolaou commentedon Mar 13, 2019
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.
pablogsal commentedon May 27, 2019
I think we can revisit this now that PEP-570 is accepted
terryjreedy commentedon May 31, 2019
Hooray! Now that PEP-570 is implemented in 3.8:
and somewhat documented, ('/' in grammar of '8.6 Function definitions', though not explained, should its status become final and listing moved?
encukou commentedon Apr 4, 2022
IMO the only thing left is to make searching for
/yield the right results, but that is bpo-15871.Closing this issue.