在哪里可以找到函数的 kwargs/args 文档

Posted 2023-03-11

【中文标题】在哪里可以找到函数的 kwargs/args 文档

【英文标题】：Where to find documentation of kwargs/args of functions

【发布时间】：2020-11-28 21:49:37

【问题描述】：

大多数库，如 requests 或 matplotlib 不包含 kwargs/args 的正确文档。有时会有示例，但大多数情况下都缺少特定的用例。

我的问题：

在哪里可以找到这些信息。 为什么开发人员没有正确记录 kwargs/args

【参考方案1】：

我只是尝试在许多类似的情况下找到源头。通常，如果没有记录，则参数将被传递给一些较低级别的函数。一旦您知道高级函数要遵循的低级函数，目的就会更有意义。

例如，查看requests.request 的文档。正如您所提到的，它表明该方法采用kwargs，但没有提及它的用途。它确实给了我们一个方便的link to the source，它显示：

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

因此，我们可以看到它是对 sessions' 实例方法 request 的一个相当薄的包装器，它只是将 kwargs 向下传递。

如果我们检查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):
    . . .

我们可以看到kwargs 得到扩展，并且应该是这些参数之一。此时，我们可以检查the documentation for that method 以更好地了解每个参数的作用。

我会注意到，如果您使用 Pycharm，您可以在符号上方 ctrl+b 跳转到其源代码，因此您不需要甚至需要追查源头进行任何侦查。

---

为什么不记录它们？人们在写东西时很懒惰和/或错过了重要的细节。他们可能已经预料到不需要记录每个细节是“足够直观的”。谁知道。有时，对于某些细节，您阅读源代码比阅读文档学到的更多。