[issue37134] [EASY] Use PEP570 syntax in the documentation

Pablo Galindo Salgado added the comment: > FWIW, there is precedent. We have type annotations in the language but don't > use them throughout the docs. Although there is some distance between both cases, I think this is an extremely good point to take into account that I have not thought

[issue37134] [EASY] Use PEP570 syntax in the documentation

Raymond Hettinger added the comment: Language features don't have rights. People do. :-) FWIW, there is precedent. We have type annotations in the language but don't use them throughout the docs. In the end, all that matters is usability. If a notion fails a usability test, then we

[issue37134] [EASY] Use PEP570 syntax in the documentation

Pablo Galindo Salgado added the comment: > If that premise turns out to be false, we should think seriously about > whether this makes the docs less approachable for everyday users. We have not done such a thing for any other feature of the language. I think that since this is now a part

[issue37134] [EASY] Use PEP570 syntax in the documentation

Pablo Galindo Salgado added the comment: > Pablo, Sure thing. I believe that a Sphinx extension (possibly existing > sphinx-tabs as suggested by @bskinn in the Steering Council issue or one we > develop/find) could give us both a "technically accurate" view and > "simplified" view. I wasn't

[issue37134] [EASY] Use PEP570 syntax in the documentation

Raymond Hettinger added the comment: I don't think inclusion in 3.9 should be automatic. The purpose of the deferment is to evaluate the premise, "the only reason people have found this notation confusing was that it wasn't yet valid syntax available for use in their own code." If that

[issue37134] [EASY] Use PEP570 syntax in the documentation

STINNER Victor added the comment: Python has many parameter types: positional-only, positional-or-keyword, keyword only, etc. Even if we don't add "/", it would be nice to have hints when we put the mouse cursor on a function parameter. Something like: function: demo(arg1, *, arg2,

[issue37134] [EASY] Use PEP570 syntax in the documentation

Carol Willing added the comment: > Could you extend your thoughts regarding this concern that I have with > respect of not including the trailing / in 3.8 but doing it in 3.9: Pablo, Sure thing. I believe that a Sphinx extension (possibly existing sphinx-tabs as suggested by @bskinn in the

[issue37134] [EASY] Use PEP570 syntax in the documentation

Change by Brian Skinn : -- nosy: +bskinn ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue37134] [EASY] Use PEP570 syntax in the documentation

Pablo Galindo Salgado added the comment: Thank you Carol for your comment! Regarding your proposal, I find it it attractive as a compromise in order to make more gentle the introduction of the feature to users. I really appreciate the effort to balance all the different aspects and

[issue37134] [EASY] Use PEP570 syntax in the documentation

Carol Willing added the comment: I echo Pablo's comment about thoughtful discourse as this is discussed. For library maintainers that are writing APIs that involve workflows across multiple projects maintained by different people, better information and documentation is very important. We

[issue37134] [EASY] Use PEP570 syntax in the documentation

Pablo Galindo Salgado added the comment: Thank you, everyone, for expressing clearly your different opinions and concerns. Without disregarding any of the arguments so far I want to make some further clarifications on some points and why I still think this is important. > FWIW, I would

[issue37134] [EASY] Use PEP570 syntax in the documentation

Grant Jenks added the comment: FWIW, I would rather not see the docs littered with "/". I've taught Python to hundreds of professional software engineers over the last five years and in all that time nobody has ever asked when the args need to be positional. It's easy to experiment to find

[issue37134] [EASY] Use PEP570 syntax in the documentation

Raymond Hettinger added the comment: > Another part of the PEP's reasoning was that this notation > is difficult to understand at least partially because it > is rarely encountered, so "people don't understand it" as > a reason to exclude it from the documentation becomes a > bit of a

[issue37134] [EASY] Use PEP570 syntax in the documentation

Paul Ganssle added the comment: > I respectfully disagree with logic, "the language now permits this, so we > should change all the docs to display it everywhere". That moves it from > optional knowledge to mandatory knowledge, from a day ten lesson to a day one > lesson, from "once in a

[issue37134] [EASY] Use PEP570 syntax in the documentation

Raymond Hettinger added the comment: I respectfully disagree with logic, "the language now permits this, so we should change all the docs to display it everywhere". That moves it from optional knowledge to mandatory knowledge, from a day ten lesson to a day one lesson, from "once in a

[issue37134] [EASY] Use PEP570 syntax in the documentation

STINNER Victor added the comment: A first enhancement would be to add an index entry for "/" at: https://docs.python.org/dev/genindex-Symbols.html > I'll note that Googling on: "python slash in formal argument list" ... We have to find a cute name for the "/ operator" in function definition!

[issue37134] [EASY] Use PEP570 syntax in the documentation

Gregory P. Smith added the comment: I agree with Brett and Carol here. This is part of the language syntax. We can educate people to that effect more if desired (I like the blog post idea). People will figure it out. We've already got high ranked stackoverflow answers related to this

[issue37134] [EASY] Use PEP570 syntax in the documentation

Carol Willing added the comment: Tim's message resonated with me. Confusing users is something that I believe that we wish to minimize. I confess that I had a similar reaction as Tim when I saw functions with a trailing `/`. What I did find helpful was adding to the middle of the parameter

[issue37134] [EASY] Use PEP570 syntax in the documentation

Brett Cannon added the comment: FYI when Guido said "call on the steering council" I think he meant open an issue at https://github.com/python/steering-council/issues as this will get lost otherwise (i.e. Guido already removed himself from the nosy list so this already doesn't have the

[issue37134] [EASY] Use PEP570 syntax in the documentation

Tim Peters added the comment: 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. Also the second, third, fourth, ..., times I saw

[issue37134] [EASY] Use PEP570 syntax in the documentation

Raymond Hettinger added the comment: > If you think me pushing for this change will impact somehow > our ability to work together I will close the PR and the issue. Not at all. I always enjoy working with you and appreciate the depth of thinking you bring to every task :-) Here, we just

[issue37134] [EASY] Use PEP570 syntax in the documentation

Change by Guido van Rossum : -- nosy: -gvanrossum ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue37134] [EASY] Use PEP570 syntax in the documentation

STINNER Victor added the comment: See also bpo-37116. -- nosy: +vstinner ___ Python tracker ___ ___ Python-bugs-list mailing list

[issue37134] [EASY] Use PEP570 syntax in the documentation

Pablo Galindo Salgado added the comment: Thank you, Raymond, for sharing your concerns regarding this. I am sorry you disagree with this change. I would want to expose the reasons I think this is important and justified, but please, don't read this as a way of dismissing your concerns; I

[issue37134] [EASY] Use PEP570 syntax in the documentation

Raymond Hettinger added the comment: Sorry, I thought that as the BDFL delegate for PEP 570, you would be the person to ask. Adding the Steering Council members to the nosy list. -- nosy: +barry, brett.cannon, ncoghlan, willingc ___ Python tracker

[issue37134] [EASY] Use PEP570 syntax in the documentation

Guido van Rossum added the comment: Please don’t call on just me. If you really don’t want this, call on the Steering Council. -- ___ Python tracker ___

[issue37134] [EASY] Use PEP570 syntax in the documentation

Raymond Hettinger added the comment: Guido, was it your intention that this show-up everywhere in the docs. I had thought the primary motivation was to make it possible to write pure python code that exactly matched a C API. ISTM, there is no need to confront every single user of the

[issue37134] [EASY] Use PEP570 syntax in the documentation

Raymond Hettinger added the comment: Do we really want to do this? ISTM, this would be a regression in the readability of the docs. 100% of the users of the docs will be confronted with this syntax which is mostly irrelevant to them. -- nosy: +rhettinger

[issue37134] [EASY] Use PEP570 syntax in the documentation

Change by Pablo Galindo Salgado : -- keywords: +patch pull_requests: +13626 stage: needs patch -> patch review pull_request: https://github.com/python/cpython/pull/13743 ___ Python tracker

[issue37134] [EASY] Use PEP570 syntax in the documentation

Change by Pablo Galindo Salgado : -- keywords: +easy stage: -> needs patch title: Use PEP570 syntax in the documentation -> [EASY] Use PEP570 syntax in the documentation type: -> enhancement ___ Python tracker