5

Most of the libraries like requests or matplotlib don't include proper documentation of kwargs/args. There are sometimes examples but mostly the specific use case is missing.

My Questions:

  1. Where can I find that sorta information.
  2. Why developers don't document the kwargs/args properly
0

1 Answer 1

4

I just try to find the source in many instances like that. Usually, if it's not documented, the args are being passed to some lower level function. Once you know what low-level function the higher-level function is deferring to, the purpose will make more sense.

For example, take a look at the docs for requests.request. As you mention, it shows that that method takes a kwargs, but doesn't mention its use. It does however give us a handy link to the source, which shows:

def request(method, url, **kwargs):
    . . .
    with sessions.Session() as session:
        return session.request(method=method, url=url, **kwargs)

So, we can see that it's a fairly thin wrapper over sessions' instance method request, where it just passes the kwargs down.

What if we check the source for that method?:

def request(self, method, url,
            params=None, data=None, headers=None, cookies=None, files=None,
            auth=None, timeout=None, allow_redirects=True, proxies=None,
            hooks=None, stream=None, verify=None, cert=None, json=None):
    . . .

We can see that the kwargs get expanded, and would be expected to be one of these parameters. At that point, we can check the documentation for that method to get a better idea about what each parameter does.

I'll note that if you're using Pycharm, you can ctrl+b over top of a symbol to jump to its source, so you don't even need to track down the source to do any sleuthing.


Why not document them? People are lazy and/or miss important details when writing things. They may have expected that it's "intuitive enough" that documenting every detail is unnecessary. Who knows. Sometimes, you learn more reading the source than you do the documentation for certain details.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.