Looks like you did the legwork of listing the params already, so you might as well send a PR with that docstring.
Re:Ask HN: Good Python codebases to read?
by Myrmornis on Thursday July 16, 2015 @02:09PM
(#9898911)
OK, maybe I will open an issue. The obvious concern is how to avoid duplicating the text among the various HTTP verb functions. In theory python allows the docstring to be manipulated via __doc__. However I don't think there is a precedent for using that mechanism to avoid duplication of docstring content that is considered good style, but perhaps someone could correct me if that is wrong.
Re:Ask HN: Good Python codebases to read?
by merlincorey on Thursday July 16, 2015 @02:34PM
(#9899071)
You'd probably want to make a metaclass that handled the manipulation of __doc__ for shared verbs if you didn't want to duplicate the data too much.
Re:Ask HN: Good Python codebases to read?
by Myrmornis on Thursday July 16, 2015 @05:40PM
(#9900032)
OK, but in requests they are top-level functions, not methods. Is there anything wrong with the below? I don't think I've seen it done.
__shared_docstring_content = """
bar
baz
"""
def f():
"f docstring"
pass
f.__doc__ += __shared_docstring_content
def g():
"g docstring"
pass
g.__doc__ += __shared_docstring_content
Re:Ask HN: Good Python codebases to read?
by andreasvc on Thursday July 16, 2015 @07:26PM
(#9900482)
I would do simply """f docstring\n%s""" % _shared_docstring, no need for a separate concatenation. However, I wonder whether sphinx would handle this.
This sort of thing works fine. We use it for pandas all the time.
Re:Ask HN: Good Python codebases to read?
by aaronchall on Friday July 17, 2015 @02:17PM
(#9904275)
Pandas does this, and I think it works well, even if it's not entirely transparent in the source.
> requests.get?
I was using Python for 8 years and IPython for somewhat 5 years if my memory serves me right but today I have learned that you can invoke help on an object by appending '?'. I guess I might delve into IPython documentation sometime.
Thank you for lengthy and detailed explanation.
The first thing many users will do is
Which tells them that it takes some kwargs, but doesn't tell them what those kwargs are. It's easy, especially for a newcomer, to read "optional arguments that `request` takes" and fail to understand that they should look up the docs on (not-really-encouraged-as-part-of-public-API) function `request`. That's pretty bad; those kwargs are important! (The reason is because requests.get is implemented as a call to request(method, ..., kwargs) but the user doesn't care what the implementation-level reason is.)Beyond that I did look into the codebase once to investigate a possible bug and there were a few python style things I wanted to fix, but I don't remember them so this comment probably sounds kind of annoying (it would annoy me if I were reading it not writing it...). It didn't strike me a really clean codebase. But yes the library is very useful and I'm sure it's a pretty decent python codebase.
Here are all the kwargs the user probably wanted to know but failed to find out and was forced to either browse online docs or the source code: