Looks good overall, I think this provides clarity to the doc.

One comment, and I'm being nitpicky here, can we use a different URL in the example, instead of xkcd? Can we use python.org as example? Or other Python-related website.

Can we use python.org as example? Or other Python-related website.

Sure. I'll tentatively put in: https://docs.python.org/3/

That URL satisfies the following useful conditions:

• is owned by Python contributors
• uses "https" rather than "http", which promotes "https"
• uses a non-trivial path "/3/" (rather than just "/")

What do you think of moving the doc for url higher up (so that order of doc paragraphs matches order of parameters), and not using a note markup (which grabs attention and takes readers out of normal reading flow)?

The example could be kept at the end, after the documentation of each parameter.

@merwok , makes sense. I'll plan to integrate those revisions later today.

Revisions integrated. Here's the updated graphical diff of the proposed changes:

Note for the dev who will merge: please edit the commit message to avoid reusing the whole original post here with its questions and screenshot

What are the next steps to move this review forward?

• This review was previously approved by python maintainers @Mariatta and @AA-Turner , but that approval was reset when I cleaned up the PR title.
• This review was also approved by @merwok. (Thanks for the helpful revisions!)

(1) Would it be helpful if I squashed/rebased this commit to the tip of the main branch?

(2) Do I need to summon someone with merge permissions? If so, is there a list of such folks publicly listed?

I will re-review later today from computer. Thanks.

The approval was reset by me actually, not a title change!

Note that all PRs for CPython are squash merged, so rebases are not needed. (In fact the devguide recommends against them, as force pushes do weird things for reviewers: ghost notifications, comments losing context)

Thanks @davidfstr for the PR, and @Mariatta for merging it 🌮🎉.. I'm working now to backport this PR to: 3.11.
🐍🍒⛏🤖