gh-85864: Add missing position-only parameters

[slateny]

#85864

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

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.

[slateny]

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

[JelleZijlstra]

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]

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]

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]

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

[miss-islington]

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]

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

[bedevere-bot]

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