Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

gh-85864: Add missing position-only parameters #91950

Merged
merged 2 commits into from Apr 30, 2022
Merged

gh-85864: Add missing position-only parameters #91950

merged 2 commits into from Apr 30, 2022

Conversation

slateny
Copy link
Contributor

@slateny slateny commented Apr 26, 2022 •
edited

#85864

One possible issue though is formatting: for example, read1 (rst here) looks something like this:

image

and I'm not sure if that's correct and I couldn't quite find any precedent to refer to.

Continuation of #91683 - turns out there are a whole lot more functions with position-only parameters than I thought, so this is how I checked them:

To get all methods in the docs with at least one parameter:

cat Doc/library/io.rst | grep method:: | grep -v '()' | cut -f6 -d' ' | cut -f1 -d'(' | sort | uniq > all_io.txt

which gives

peek
read
read1
readinto
readinto1
readline
readlines
reconfigure
seek
truncate
write
writelines

Then of those methods, get all methods that don't have trailing position-only markers:

cat all_io.txt | xargs -n1 -I {} grep -r '{}(\$' Modules/_io/clinic/ | grep -v '/)\\n'

which gave reconfigure, the only method with parameters that doesn't have position-only parameters. Then to confirm that the docs do note that all methods with parameters have the marker:

cat Doc/library/io.rst | grep method:: | grep -v '()' | grep -v '/'

which outputs configure, which matches. Functions/classes were checked manually since there were fewer.

@bedevere-bot bedevere-bot added docs Documentation in the Doc dir awaiting review labels Apr 26, 2022
@slateny
Copy link
Contributor Author

slateny commented Apr 26, 2022 •
edited

@JelleZijlstra Could you take a look at this follow-up? Main question I have is just on the formatting (the screenshot)

@slateny slateny changed the title gh-85864: Added missing position-only parameters gh-85864: Add missing position-only parameters Apr 26, 2022
@JelleZijlstra JelleZijlstra self-assigned this Apr 26, 2022
@JelleZijlstra
Copy link
Member

JelleZijlstra commented Apr 26, 2022

Thanks, looks good. Thanks also for the explanation of the script you ran.

Do we document what the [size] syntax means exactly? If it already implies positional-only, we can skip the /.

@slateny
Copy link
Contributor Author

slateny commented Apr 27, 2022

This doesn't say anything about position-only, so it might still be needed, though the slash does look a bit odd with the brackets

@slateny
Copy link
Contributor Author

slateny commented Apr 29, 2022

Also related: #91485 (comment)

So maybe the way forward is to just document all default values instead of leaving them empty with square brackets

@JelleZijlstra
Copy link
Member

JelleZijlstra commented Apr 29, 2022

Agree, if there's a sensible default value we can show we should avoid the [] syntax.

@JelleZijlstra JelleZijlstra merged commit 3a8e2b6 into python:main Apr 30, 2022
13 checks passed
@miss-islington
Copy link
Contributor

miss-islington commented Apr 30, 2022

Thanks @slateny for the PR, and @JelleZijlstra for merging it 🌮🎉.. I'm working now to backport this PR to: 3.9, 3.10.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

@bedevere-bot
Copy link

bedevere-bot commented Apr 30, 2022

GH-92085 is a backport of this pull request to the 3.10 branch.

@bedevere-bot
Copy link

bedevere-bot commented Apr 30, 2022

GH-92086 is a backport of this pull request to the 3.9 branch.

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request Apr 30, 2022
@slateny @miss-islington
pythongh-85864: io docs: Add missing position-only parameters (python…
6892206 
…GH-91950)

(cherry picked from commit 3a8e2b6)

Co-authored-by: slateny <46876382+slateny@users.noreply.github.com>
miss-islington added a commit that referenced this pull request Apr 30, 2022
@miss-islington @slateny
gh-85864: io docs: Add missing position-only parameters (GH-91950)
5ed9556 
(cherry picked from commit 3a8e2b6)

Co-authored-by: slateny <46876382+slateny@users.noreply.github.com>
miss-islington added a commit that referenced this pull request Apr 30, 2022
@miss-islington @slateny
gh-85864: io docs: Add missing position-only parameters (GH-91950)
2c859e3 
(cherry picked from commit 3a8e2b6)

Co-authored-by: slateny <46876382+slateny@users.noreply.github.com>
@slateny slateny deleted the s/io branch May 4, 2022
@slateny slateny mentioned this pull request Jun 1, 2022
Closed
hello-adam pushed a commit to hello-adam/cpython that referenced this pull request Jun 2, 2022
@miss-islington @slateny @hello-adam
pythongh-85864: io docs: Add missing position-only parameters (python…
da83e1b 
…GH-91950)

(cherry picked from commit 3a8e2b6)

Co-authored-by: slateny <46876382+slateny@users.noreply.github.com>
@slateny slateny mentioned this pull request Jul 20, 2022
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@JelleZijlstra JelleZijlstra

Assignees

@JelleZijlstra JelleZijlstra

Labels
docs Documentation in the Doc dir skip news
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
5 participants
@slateny @JelleZijlstra @miss-islington @bedevere-bot @AlexWaygood