gh-101536: [docs] Improve attributes of urllib.error.HTTPError#101612
Conversation
| .. attribute:: url | ||
|
|
||
| Contains the request URL. | ||
| Is an alias for *filename* attribute. |
There was a problem hiding this comment.
Maybe more concisely, the 'Is' can be dropped here and below? Not sure which style's better though.
There was a problem hiding this comment.
I am not a native speaker, so I am fine with any decision, which sounds better :)
There was a problem hiding this comment.
Not English native speaker either, but "Alias for ..." sounds better to me.
|
My 2 cents: it seems like the shorter property names should be discouraged: the variable names are more cryptic to read in code and might confuse developers/laypeople who don’t know what the shorthand means. |
Yes, this exactly what I was thinking. That's why I went with the longer and more semantic names in the docs. |
facundobatista
left a comment
facundobatista
left a comment
There was a problem hiding this comment.
Hello! Thanks for this work. I added a minor detail here.
Regarding your questions, we need to document everything that is public. I like the approach you took of listing first the "good names", declaring the others as aliases.
|
|
||
| .. attribute:: fp | ||
|
|
||
| A file-like object with the HTTP error body. |
There was a problem hiding this comment.
The file like object does not have the body, you can read from it. I'd write something like "A file-like object where the HTTP error body can be read from."
|
A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated. Once you have made the requested changes, please leave a comment on this pull request containing the phrase |
|
I have made the requested changes; please review again Thanks everyone! |
|
Thanks for making the requested changes! @facundobatista: please review the changes made to this pull request. |
|
Thank you so very much everyone!!! |
6 participants
There are several tricky parts:
urlandfilename,hdrsandheaders,codeandstatus,msgand readonlyreason. Which ones should we document? My idea was that we should try to stick to the same names we use in constructor. But, with some exceptions. For example:filenamedoes not make much sense here: I changed it to beurl. And the same withmsgandhdrs: I usereasonandheadersmsgandreasonare the same thingCC @facundobatista @orsenthil