classification
Title: Clarify Protocol Handlers in urllib.request Docs
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Denton-L, cheryl.sabella, docs@python, miss-islington, mrabarnett, orsenthil, terry.reedy
Priority: normal Keywords: patch

Created on 2018-11-03 23:11 by Denton-L, last changed 2019-03-22 23:30 by miss-islington.

Pull Requests
URL Status Linked Edit
PR 10313 merged Denton-L, 2018-11-03 23:12
PR 12502 merged miss-islington, 2019-03-22 23:24
PR 12503 closed miss-islington, 2019-03-22 23:24
Messages (15)
msg329210 - (view) Author: Denton Liu (Denton-L) * Date: 2018-11-03 23:11
The urllib.request documentation that they can add their own protocol handlers, however they are unclear on how they should be named. We should replace instances of things like protocol_request with <protocol>_request to make it clear that we are literally replacing "protocol" with the literal protocol.

I am creating this issue because I had to actually read the urllib.request source code in order to figure out how to use the protocol handler APIs.
msg330923 - (view) Author: Denton Liu (Denton-L) * Date: 2018-12-03 09:42
Pinging for updates.
msg332714 - (view) Author: Denton Liu (Denton-L) * Date: 2018-12-29 12:12
Pinging again for updates. Would appreciate a PR review. Thanks!
msg335365 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-02-12 20:15
Cheryl, you know rst better than me.  Is there any markup to indicate that a word is a placeholder, not meant to be taken literally?  Or is Denton's '<placeholder>' instead of 'placeholder' the best choice? See the PR and answer there.
msg335371 - (view) Author: Matthew Barnett (mrabarnett) * (Python triager) Date: 2019-02-12 21:46
You could italicise the "protocol" part using asterisks, like this:

*protocol*_request

or this:

*protocol*\ _request

depending on the implementation of the rst software.
msg335373 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-02-12 22:32
I don't think there is anything specifically defined for a placeholder.  However, looking at the current urllib.request documentation, there are 2 places that use the ``<name>_`` method for a placeholder - <protocol>.proxy and <scheme>.proxy, with the latter explaining what <scheme> means.

> By default, ProxyHandler uses the environment variables named <scheme>_proxy, where <scheme> is the URL scheme involved.

That line was added by Georg Brandl (granted it was part of converting all the docs), which would lead me to believe that is the accepted way to do it.

Also, the argument clinic how-to has the following:
> The length of the string will be passed in to the impl function, just after the string parameter, as a parameter named ``<parameter_name>_length``.

I'll make a comment on the PR too.
msg335383 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-02-13 02:33
unittest is another module with half-fixed and half-variable names.  The default (glob) pattern for test module names is given as "test*.py".  The fixed pattern for test methods is given as "starts with 'test'".  This could have been given, I believe, as re "test/w*", but it wasn't.  The former is clearer for more people.  So no guidance there.

I agree that we should follow the 2 precedents. Thank you both.
msg335487 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-02-14 01:01
I found this issue that Serhiy did on the devguide where he added {} around the placeholder:
https://github.com/python/devguide/pull/444

I think that might be the correct way to do it.
msg335490 - (view) Author: Denton Liu (Denton-L) * Date: 2019-02-14 01:39
I gave that a try but it seems like it just outputs the {} literally in the
case of the method role.
msg335494 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2019-02-14 04:54
For file names, the result is <name> in italics.  Looking at https://devguide.python.org/exploring/, that seems to work well.  Can we just use *<name>*?
msg335504 - (view) Author: Denton Liu (Denton-L) * Date: 2019-02-14 07:32
Unfortunately, inline markup can't be combined with roles. Using asterisks, it shows up as `*<protocol>*_open()` and using braces, `{<protocol>}_open`.

I'm not sure how this works but it _might_ be possible to change how :meth: role is interpreted but I believe that's outside the scope of this change.
msg335990 - (view) Author: Denton Liu (Denton-L) * Date: 2019-02-19 18:02
If there aren't anymore comments, I think this PR is ready for a second round of reviews.

Thanks!
msg338617 - (view) Author: miss-islington (miss-islington) Date: 2019-03-22 21:49
New changeset dd7c4ceed90792f711347024852d4cf883a9ab9e by Miss Islington (bot) (Denton Liu) in branch 'master':
bpo-35155: clarify protocol handler method naming (GH-10313)
https://github.com/python/cpython/commit/dd7c4ceed90792f711347024852d4cf883a9ab9e
msg338624 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2019-03-22 23:24
We could backport this to older versions too. This documentation change is helpful, and backporting this will help with future backport patches against these files.
msg338625 - (view) Author: miss-islington (miss-islington) Date: 2019-03-22 23:30
New changeset 868581ee7687ad25af70c0cb9cd6a0f2077e6422 by Miss Islington (bot) in branch '3.7':
bpo-35155: clarify protocol handler method naming (GH-10313)
https://github.com/python/cpython/commit/868581ee7687ad25af70c0cb9cd6a0f2077e6422
History
Date User Action Args
2019-03-22 23:30:06miss-islingtonsetmessages: + msg338625
2019-03-22 23:24:47miss-islingtonsetpull_requests: + pull_request12452
2019-03-22 23:24:36miss-islingtonsetstage: resolved -> patch review
pull_requests: + pull_request12451
2019-03-22 23:24:14orsenthilsetstatus: closed -> open

messages: + msg338624
2019-03-22 22:51:32Denton-Lsetstatus: open -> closed
stage: patch review -> resolved
2019-03-22 21:49:57miss-islingtonsetnosy: + miss-islington
messages: + msg338617
2019-02-19 18:02:45Denton-Lsetmessages: + msg335990
2019-02-14 07:32:12Denton-Lsetmessages: + msg335504
2019-02-14 04:54:42terry.reedysetmessages: + msg335494
2019-02-14 01:39:20Denton-Lsetmessages: + msg335490
2019-02-14 01:01:54cheryl.sabellasetmessages: + msg335487
2019-02-13 02:33:50terry.reedysetmessages: + msg335383
2019-02-12 22:32:24cheryl.sabellasetmessages: + msg335373
2019-02-12 21:46:51mrabarnettsetnosy: + mrabarnett
messages: + msg335371
2019-02-12 20:15:16terry.reedysetnosy: + cheryl.sabella, terry.reedy, orsenthil

messages: + msg335365
versions: - Python 3.4, Python 3.5, Python 3.6
2018-12-29 12:12:24Denton-Lsetmessages: + msg332714
2018-12-03 09:42:23Denton-Lsetmessages: + msg330923
2018-11-03 23:12:47Denton-Lsetkeywords: + patch
stage: patch review
pull_requests: + pull_request9616
2018-11-03 23:11:13Denton-Lcreate