bpo-35155: clarify protocol handler method naming by Denton-L · Pull Request #10313 · python/cpython (original) (raw)

I don't think there is a defined way to markup a placeholder. Currently, urllib.request uses <protocol>_ and <scheme>_ in other parts of the document. In addition, the argument clinic how-to uses a similar <parameter_name>_length. Since a name can't start with <, this seems reasonable.

For urllib.request docs under the BaseHandler Objects section, the error method is defined as:
BaseHandler.http_error_nnn(req, fp, code, msg, hdrs) and then states nnn should be a three-digit HTTP error code.

Interestingly, these methods listed under OpenerDirector are supposed to be defined as part of the handler class passed in to OpenerDirector and those methods are defined (without the <protocol>) under BaseHandler. IMHO, the listing of the methods in OpenerDirector should link to those definitions under BaseHandler.

I also don't think the links are correct when BaseHandler or OpenerDirector are clicked anywhere within the doc. They link to the class definition, which doesn't say much. All the meat is under the Objects sections for each of those classes (which are also in the ToC on the left), so it would more helpful for links to go to those sections. If that happened (linking the methods under OpenerDirector to BaseHandler), then BaseHandler could better explain that protocol is a placeholder.