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.

Pinging for updates.

Pinging again for updates. Would appreciate a PR review. Thanks!

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.

You could italicise the "protocol" part using asterisks, like this:

*protocol*_request

or this:

*protocol*\ _request

depending on the implementation of the rst software.

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.

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.

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.

I gave that a try but it seems like it just outputs the {} literally in the
case of the method role.

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>*?

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.

If there aren't anymore comments, I think this PR is ready for a second round of reviews.

Thanks!

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

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.

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

This seems complete, can it be closed?

messages: + msg338624

messages: + msg335365
versions: - Python 3.4, Python 3.5, Python 3.6