[issue35155] Clarify Protocol Handlers in urllib.request Docs
New submission from Denton Liu <liu.denton@gmail.com>: 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. ---------- assignee: docs@python components: Documentation messages: 329210 nosy: Denton-L, docs@python priority: normal severity: normal status: open title: Clarify Protocol Handlers in urllib.request Docs type: enhancement versions: Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Change by Denton Liu <liu.denton@gmail.com>: ---------- keywords: +patch pull_requests: +9616 stage: -> patch review _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Denton Liu <liu.denton@gmail.com> added the comment: Pinging for updates. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Denton Liu <liu.denton@gmail.com> added the comment: Pinging again for updates. Would appreciate a PR review. Thanks! ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: 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. ---------- nosy: +cheryl.sabella, orsenthil, terry.reedy versions: -Python 3.4, Python 3.5, Python 3.6 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Matthew Barnett <python@mrabarnett.plus.com> added the comment: You could italicise the "protocol" part using asterisks, like this: *protocol*_request or this: *protocol*\ _request depending on the implementation of the rst software. ---------- nosy: +mrabarnett _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Cheryl Sabella <cheryl.sabella@gmail.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Cheryl Sabella <cheryl.sabella@gmail.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Denton Liu <liu.denton@gmail.com> added the comment: I gave that a try but it seems like it just outputs the {} literally in the case of the method role. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: 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>*? ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Denton Liu <liu.denton@gmail.com> added the comment: 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. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Denton Liu <liu.denton@gmail.com> added the comment: If there aren't anymore comments, I think this PR is ready for a second round of reviews. Thanks! ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: 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/dd7c4ceed90792f711347024852d4cf883a... ---------- nosy: +miss-islington _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Change by Denton Liu <liu.denton@gmail.com>: ---------- stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Senthil Kumaran <senthil@uthcode.com> added the comment: 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. ---------- status: closed -> open _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +12451 stage: resolved -> patch review _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Change by miss-islington <mariatta.wijaya+miss-islington@gmail.com>: ---------- pull_requests: +12452 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
miss-islington <mariatta.wijaya+miss-islington@gmail.com> added the comment: 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/868581ee7687ad25af70c0cb9cd6a0f2077... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Irit Katriel <iritkatriel@yahoo.com> added the comment: This seems complete, can it be closed? ---------- nosy: +iritkatriel _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
Change by Terry J. Reedy <tjreedy@udel.edu>: ---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue35155> _______________________________________
participants (7)
-
Cheryl Sabella -
Denton Liu
-
Irit Katriel
-
Matthew Barnett
-
miss-islington
-
Senthil Kumaran
-
Terry J. Reedy