[issue37134] Use PEP570 syntax in the documentation

[miss-islington]

miss-islington  added the comment:


New changeset dba4448c63b687204813a5b04c89dd458d5ac45b by Miss Islington (bot) 
in branch '3.8':
bpo-37134: Add PEP570 notation to the signature of byte{array}.translate 
(GH-13874)
https://github.com/python/cpython/commit/dba4448c63b687204813a5b04c89dd458d5ac45b


--

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[miss-islington]

Change by miss-islington :


--
pull_requests: +13753
pull_request: https://github.com/python/cpython/pull/13875

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Pablo Galindo Salgado]

Pablo Galindo Salgado  added the comment:


New changeset de76c07a8cd0216c3dce215e4d542e2f45aa022f by Pablo Galindo in 
branch 'master':
bpo-37134: Add PEP570 notation to the signature of byte{array}.translate 
(GH-13874)
https://github.com/python/cpython/commit/de76c07a8cd0216c3dce215e4d542e2f45aa022f


--

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Pablo Galindo Salgado]

Change by Pablo Galindo Salgado :


--
pull_requests: +13752
pull_request: https://github.com/python/cpython/pull/13874

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[STINNER Victor]

STINNER Victor  added the comment:

It seems like the translate() method of bytes and bytearray also needs a "/" in 
their doc.

I wrote a quick & dirty script to parse C files:
---
import glob

def parse(filename):
clinic_input = False
args = False
positional = False
func = None
for line_number, line in enumerate(open(filename)):
line = line.rstrip()
if line.startswith("/*[clinic input]"):
clinic_input = True
args = False
positional = False
func = None
elif clinic_input and func is None:
func = line
elif clinic_input and not args and not line:
args = True
elif args and line == "/":
positional = True
elif positional and (line == "*" or line.startswith("[clinic start 
generated code]")):
clinic_input = False
args = False
positional = False
func = None
elif positional and line:
print("!!!", filename, line_number, func, repr(line))
elif not line:
clinic_input = False
args = False
positional = False
func = None

for filename in glob.glob("*/**.c"):
parse(filename)
---

Output on the master branch:
---
!!! Modules/_struct.c 2224 unpack_from 'buffer: Py_buffer'
!!! Modules/_struct.c 2225 unpack_from 'offset: Py_ssize_t = 0'
!!! Modules/zlibmodule.c 195 zlib.compress 'level: 
int(c_default="Z_DEFAULT_COMPRESSION") = Z_DEFAULT_COMPRESSION'
!!! Modules/zlibmodule.c 196 zlib.compress 'Compression level, in 0-9 
or -1.'
!!! Modules/zlibmodule.c 314 zlib.decompress 'wbits: 
int(c_default="MAX_WBITS") = MAX_WBITS'
!!! Modules/zlibmodule.c 315 zlib.decompress 'The window buffer size 
and container format.'
!!! Modules/zlibmodule.c 316 zlib.decompress 'bufsize: 
ssize_t(c_default="DEF_BUF_SIZE") = DEF_BUF_SIZE'
!!! Modules/zlibmodule.c 317 zlib.decompress 'The initial output buffer 
size.'
!!! Modules/zlibmodule.c 744 zlib.Decompress.decompress 'max_length: 
ssize_t = 0'
!!! Modules/zlibmodule.c 745 zlib.Decompress.decompress 'The maximum 
allowable length of the decompressed data.'
!!! Modules/zlibmodule.c 746 zlib.Decompress.decompress 'Unconsumed 
input data will be stored in'
!!! Modules/zlibmodule.c 747 zlib.Decompress.decompress 'the 
unconsumed_tail attribute.'
!!! Objects/bytearrayobject.c 1197 bytearray.translate 'delete as 
deletechars: object(c_default="NULL") = b\'\''
!!! Objects/bytesobject.c 2080 bytes.translate 'delete as deletechars: 
object(c_default="NULL") = b\'\''
!!! Python/bltinmodule.c 2282 sum as builtin_sum 'start: 
object(c_default="NULL") = 0'
---

--

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Pablo Galindo Salgado]

Pablo Galindo Salgado  added the comment:

Thanks Brian for the prototype!

I will close this now. We can reopen if something is missing in the future.

--
resolution:  -> fixed
stage: patch 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

[issue37134] Use PEP570 syntax in the documentation

[Guido van Rossum]

Guido van Rossum  added the comment:

Thanks Brian!

--

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Brian Skinn]

Brian Skinn  added the comment:

:thumbsup:

Glad I happened to be in the right place at the right time to put it together. 
I'll leave the tabslash repo up for future reference.

--

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Carol Willing]

Carol Willing  added the comment:

@brian, Just to echo Brett's words, the Steering Council appreciated the tabbed 
prototype and your effort to create it. While we may not use it in this 
particular case, it's great to keep in mind for other places. Thanks for 
contributing :D

--

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Brett Cannon]

Brett Cannon  added the comment:

@Brian: And thanks for the experiment! It was an interesting idea to consider.

--

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Brett Cannon]

Brett Cannon  added the comment:

@Brian: Probably not. The worry that came up during the steering council 
meeting was bifurcating the docs could cause confusion as to why it was 
different, which one was more "right", etc.

--

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Brian Skinn]

Brian Skinn  added the comment:

Brett, to be clear, this sounds like the tabbed solution is not going to be 
used at this point? If so, I'll pull down the tabbed docs I'm hosting.

--

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[miss-islington]

miss-islington  added the comment:


New changeset 23f41a64ea668296fa89e25f3cfa11f63026ecac by Miss Islington (bot) 
in branch '3.8':
bpo-37134: Use PEP570 syntax for sum() (GH-13851)
https://github.com/python/cpython/commit/23f41a64ea668296fa89e25f3cfa11f63026ecac


--
nosy: +miss-islington

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[miss-islington]

Change by miss-islington :


--
pull_requests: +13730
pull_request: https://github.com/python/cpython/pull/13854

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Pablo Galindo Salgado]

Pablo Galindo Salgado  added the comment:


New changeset c4c421d619baf2ff2f7e09f55b7ae22b8f863c7b by Pablo Galindo in 
branch 'master':
bpo-37134: Use PEP570 syntax for sum() (GH-13851)
https://github.com/python/cpython/commit/c4c421d619baf2ff2f7e09f55b7ae22b8f863c7b


--

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Pablo Galindo Salgado]

Change by Pablo Galindo Salgado :


--
pull_requests: +13728
pull_request: https://github.com/python/cpython/pull/13851

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Guido van Rossum]

Guido van Rossum  added the comment:

IIUC sum() should also have a slash in the middle.

--
nosy: +gvanrossum

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Gregory P. Smith]

Change by Gregory P. Smith :


--
nosy:  -gregory.p.smith

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Carol Willing]

Carol Willing  added the comment:


New changeset 54edb04aa688c8247570b4f59b5145e3fa417576 by Carol Willing (Pablo 
Galindo) in branch 'master':
bpo-37134: Add PEP570 notation to the documentation (GH-13743)
https://github.com/python/cpython/commit/54edb04aa688c8247570b4f59b5145e3fa417576


--

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Pablo Galindo Salgado]

Pablo Galindo Salgado  added the comment:

Thank you very much, everyone, for sharing your comments, views and concerns 
and thanks to the steering council for helping to reach a conclusion. 

I have updated PR13743 to only modify the functions that fall into the second 
point of Brett's message as indicated.

--

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[STINNER Victor]

Change by STINNER Victor :


--
nosy: +vstinner

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[STINNER Victor]

Change by STINNER Victor :


--
nosy:  -vstinner

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Brett Cannon]

Brett Cannon  added the comment:

To help short-circuit this discussion and focus on the desired solution, the 
steering council came to a decision that can be seen at 
https://github.com/python/steering-council/issues/12#issuecomment-498874939 :

- for Python 3.8 specifically, we think it makes sense to continue to leave the 
slashes out of the documentation for the all parameters are positional-only 
case (i.e. "... , /)") and the all parameters are positional-only & 
keyword-only case (i.e. "..., /, *, ..." and "..., /, *args, ..."). This 
question can then be revisited for Python 3.9.

- however, we actively want to see them added for the cases where an API has a 
mixture of positional-only and positional-or-keyword args (i.e. "..., /, ...")

- we'd like to see the rendered documentation for function signatures enhanced 
to use tooltips to name the positional-only (bare "/"), keyword-only (bare 
"*"), additional positional args (named "*"), and additional keyword args 
(named "**") notations (hyperlinking to a glossary entry could also be 
interesting, but may be too visually noisy based on how the hyperlinks get 
rendered)

--

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Brian Skinn]

Brian Skinn  added the comment:

First, for anyone interested, there are screenshots and links to docs versions 
at the SC GH issue 
(https://github.com/python/steering-council/issues/12#issuecomment-498856524, 
and following) where we're exploring what the tabbed approach to the PEP570 
docs might look like.

Second, I'd like to suggest an additional aspect of the docs situation for 
consideration.

Regardless of which specific approach is decided upon here, it seems likely the 
consensus will be a course of action requiring touching the majority 
(entirety?) of the stdlib API docs. Currently, all of the API docs are manually 
curated in the .rst, at minimum for the reasons laid out by Victor in bpo25461 
(https://bugs.python.org/issue25461#msg253381). If there's any chance that the 
balance of factors has changed such that using autodoc (or similar) *would* now 
be preferable, IWSTM that now is a good time to have that discussion, so that 
an autodoc conversion could be done at the same time as the PEP570 rework.

--

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Serhiy Storchaka]

Serhiy Storchaka  added the comment:

You need to use the PEP 570 syntax if your function/method have a var-keyword 
parameter, takes arbitrary keyword arguments, and has other parameters beside 
the var-keyword parameter ("self" counts). And of course the minimal supported 
Python version should be 3.8.

In PR 13700 the PEP 570 syntax was added in the documentation of functions that 
use it in the code (like partial() and getcallargs()) and also in the examples 
of user code where it is needed (like LRU, Callback and Namespace).

PR 13743 adds it the documentation of functions which do not accept arbitrary 
keywords, but take some of arguments as positional only and others as 
positional or keyword. It may be surprising, so I think it is better to 
document this explicitly.

--

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Grant Jenks]

Grant Jenks  added the comment:

Pablo, I never intended disrespect toward you personally. And I am sorry my 
words came across that way. I would rather the feature be one of Python's more 
esoteric qualities.

I think Carol has described the most reasonable way forward. And in particular, 
I like this creative idea:

> A Sphinx extension may also be made to show a simple user-friendly view and 
> with a click the fully accurate view.

I agree too with Raymond in this point:

> I don't think inclusion in 3.9 should be automatic.

As anecdata: I showed the PEP and feature to an intermediate class of 15 
professional software engineers today. The first question I got was, "when 
should I use that in my Python code?" And I think the answer is rarely. We 
reviewed the motivating cases in the PEP and those made sense to them. But I 
was left feeling concern that if it were prominent and frequent in the docs 
then people will be likely to imitate, not least of which through simple 
copy/paste, what they see there without understanding the C-API and why it is 
that way.

--

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[STINNER Victor]

STINNER Victor  added the comment:

Tim Peters: "I haven't looked at anything in this PR, so just popping in to 
confirm that the first time I saw stuff like: len(obj, /) in the docs I had no 
idea at all what it was trying to say.  I thought it was a typo. (...)"

Carol Willing: "I confess that I had a similar reaction as Tim when I saw 
functions with a trailing `/`."

I'm quite sure that many users have same reaction the first time they meet 
"@decorator", "*args", "def func(*, arg)", etc. PEP 570 introduces a syntax 
which was still illegal in Python 3.7, so it's normal to be surprised when we 
meet a new syntax.

In a few years, people will be used to that, but will be surprised by yet 
another new syntax ;-)

The best we can do is to enhance the documentation to properly document "/", 
directly in the reference documentation. Sphinx is a great help to add links. 
And we can maybe extend Sphinx to add even more inline hints.

--

The "/" character was discussed in length in the PEP 570. Many people 
complained... but nobody succeed to came up with a better syntax. The PEP has 
been accepted and its now part of the *Python language*.

As explained in length in the PEP 570, the "/" syntax is *not* new. For 
example, it is used for years in Python docstrings. Paul Ganssle also mentioned 
that this notation is "already used in the numpy documentation IIRC".

--

I don't think that we must hide some syntax like "*args" or "def func(*, arg)" 
from the doc, just because people learning Python might be surprised at the 
first read. I don't think that the reference documentation should be used to 
learn Python. They are way better resources than that to learn Python. 
Moreover, it's not really written like a tutorial. We have some 
https://docs.python.org/dev/howto/ for that.

>From my point of view, the *reference* documentation is more used by people 
>who are already used to Python and so know the Python syntax. Trying to hide 
>the real API in the *reference* documentation sounds weird (wrong) to me. The 
>doc should document the real behavior. The PEP 570 makes is possible, whereas 
>previously, the doc was lying.

If you consider that "len(obj, /)" is a typo, maybe we must fix len to accept 
obj as a keyword parameter? But they are good reasons why it's a positional 
only parameter. I don't think that anyone wants to change that. The current 
trend is more the opposite: convert some positional-or-keyword parameters to 
positional-only parameters, especially for functions taking a single parameter.

In short, I concur with Brett who wrote:

> Anyway, from my personal view, I think we should use the syntax. It's 
> officially part of the language at this point and so avoiding it in the docs 
> seems odd, like we're saying that we're ashamed of this syntax and you should 
> pretend it doesn't exist when it does and it isn't going anywhere. Otherwise 
> aren't we're forcing users to realize that the function definition in the 
> docs deviates from what is definable in this one instance and that one has to 
> read the full text to know that something is doable syntactically but we're 
> leaving it out of the docs? It adds inconsistency in what the definition line 
> means IMO based on how we have usually chosen to try and express things in 
> that 'def' line in the docs as succinctly as possible to communicate the 
> semantics of calling that function.

--

By the way, PR 13743 doesn't modify every single function of the documentation. 
Only a few files are modified, simply because only few functions accept 
positional-only parameters. My expectation is more that nobody will notice :-)

--
keywords:  -easy
nosy: +serhiy.storchaka

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Julien Palard]

Julien Palard  added the comment:

FWIW here's my feedback (as a Python teacher and doc guy):

I find that newcomers are good to ignore what they don't understand, so a 
newcomer exposed to "foo(a, b, /)" will no run away nor cry, he will just 
ignore the slash and understand that "foo takes two parameters, a and b" and be 
happy with it.

Then I think that for more advanced people it's nice to have it:

- It's a way to discover it's a valid syntax
- It's a usefull information to use
- It does not take a lot of space
- It's the truth (I mean, displaying "foo(a, b)" for "foo(a, b, /)" is a kind 
of a lie, I don't like it)

So I'm +1 for using PEP570 syntax in the documentation.

--
nosy: +mdk

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Pablo Galindo Salgado]

Change by Pablo Galindo Salgado :


--
title: [EASY] Use PEP570 syntax in the documentation -> Use PEP570 syntax in 
the documentation

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[STINNER Victor]

Change by STINNER Victor :


--
keywords:  -easy
title: [EASY] Use PEP570 syntax in the documentation -> Use PEP570 syntax in 
the documentation

___
Python tracker 

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

[issue37134] Use PEP570 syntax in the documentation

[Pablo Galindo Salgado]

New submission from Pablo Galindo Salgado :

In the documentation, there are a lot of mismatches regarding function and 
method signatures that use positional-only arguments with respect to the 
docstrings (that properly use PEP570 syntax for documenting positional-only 
parameters).

Not that the official syntax for positional-only parameters is accepted (the 
"/"), the documentation needs to be updated to reflect positional-only 
parameters in the functions and methods that use them as covered in the PEP 
document.

--
assignee: docs@python
components: Documentation
messages: 344295
nosy: docs@python, pablogsal
priority: normal
severity: normal
status: open
title: Use PEP570 syntax in the documentation
versions: Python 3.8

___
Python tracker 

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