[issue21314] Document '/' in signatures

[Petr Viktorin]

Petr Viktorin  added the comment:

- PEP 570 (Python Positional-Only Parameters) is final
- The language spec was updated to mention it
- the FAQ entry was revised to not link to the PEP and be a self-contained 
explanation

IMO the only thing left is to make searching for `/` yield the right results, 
but that is bpo-15871.
Closing this issue.

--
nosy: +petr.viktorin
resolution:  -> fixed
stage: commit review -> resolved
status: open -> closed

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Terry J. Reedy]

Terry J. Reedy  added the comment:

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?

--
nosy: +terry.reedy

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Pablo Galindo Salgado]

Pablo Galindo Salgado  added the comment:

I think we can revisit this now that PEP570 is accepted

--
nosy: +pablogsal

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Lysandros Nikolaou]

Lysandros Nikolaou  added the comment:

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.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Cheryl Sabella]

Cheryl Sabella  added the comment:

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.

--
nosy: +cheryl.sabella

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Nick Coghlan]

Nick Coghlan  added the comment:

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)

--
nosy: +rhettinger -miss-islington
stage: patch review -> commit review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[miss-islington]

miss-islington  added the comment:


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


--
nosy: +miss-islington

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[miss-islington]

Change by miss-islington :


--
pull_requests: +12250

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Nick Coghlan]

Nick Coghlan  added the comment:


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


--
nosy: +ncoghlan

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Lysandros Nikolaou]

Lysandros Nikolaou  added the comment:

Ping for review.

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Yury Selivanov]

Change by Yury Selivanov :


--
nosy:  -yselivanov

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Lysandros Nikolaou]

Change by Lysandros Nikolaou :


--
keywords: +patch, patch, patch
pull_requests: +9891, 9892, 9893
stage: needs patch -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Lysandros Nikolaou]

Change by Lysandros Nikolaou :


--
keywords: +patch, patch
pull_requests: +9891, 9892
stage: needs patch -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Lysandros Nikolaou]

Change by Lysandros Nikolaou :


--
keywords: +patch
pull_requests: +9891
stage: needs patch -> patch review

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Noah Haasis]

Noah Haasis  added the comment:

I don‘t have the time right now. Feel free to work on it!

--

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Lysandros Nikolaou]

Lysandros Nikolaou  added the comment:

Noah, are you working on this?

--
nosy: +lys.nikolaou

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Pradyun Gedam]

Pradyun Gedam  added the comment:

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/

--
nosy: +pradyunsg

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Berker Peksag]

Berker Peksag  added the comment:

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.

--
versions: +Python 3.6, Python 3.7, Python 3.8 -Python 3.4, Python 3.5

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Noah Haasis]

Noah Haasis  added the comment:

Can I work on this?

--
nosy: +noah.haasis

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Berker Peksag]

Berker Peksag  added the comment:

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.

--
nosy: +berker.peksag

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Jakub Wilk]

Change by Jakub Wilk :


--
nosy: +jwilk

___
Python tracker 

___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Serhiy Storchaka]

Changes by Serhiy Storchaka storch...@gmail.com:


--
components: +Argument Clinic

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue21314
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Zachary Ware]

Zachary Ware added the comment:

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)

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue21314
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Emily Zhao]

Emily Zhao added the comment:

Can someone close this? I think it's fixed.

--
nosy: +emily.zhao

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue21314
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Benjamin Peterson]

Benjamin Peterson added the comment:

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.

--
nosy: +benjamin.peterson

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue21314
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Emily Zhao]

Emily Zhao added the comment:

where's the best place for that documentation to live?

--

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue21314
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Zachary Ware]

Changes by Zachary Ware zachary.w...@gmail.com:


--
keywords: +easy
stage:  - needs patch
status:  - open
type:  - enhancement
versions: +Python 3.5

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue21314
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com

[issue21314] Document '/' in signatures

[Terry J. Reedy]

Changes by Terry J. Reedy tjre...@udel.edu:


--
status: open - 
title: Bizarre help - Document '/' in signatures

___
Python tracker rep...@bugs.python.org
http://bugs.python.org/issue21314
___
___
Python-bugs-list mailing list
Unsubscribe: 
https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com