[x]* 在 python 函数文档中是什么意思？答案

【问题标题】：What does [x]* mean in python function documention?[x]* 在 python 函数文档中是什么意思？
【发布时间】：2019-09-03 10:25:34
【问题描述】：

我想在 python 3 中为 urllib.request.urlopen 指定一个超时参数。

docs 说：

urllib.request.urlopen(url, data=None, [timeout, ]*, cafile=None, capath=None, cadefault=False, context=None)

[timeout, ]* 是什么意思？

我认为所有可选的命名参数（data=None、cafile=None ...）都必须出现在所有未命名参数之前。

这里看起来timeout 是一个未命名的参数。但它出现在之后 data。

只看那个文档，我不知道是否要使用：

urlopen(url, 123)
urlopen(url, timeout=123)
urlopen(url, [123])
urlopen(url, [123]*)

我可以从this post 看到正确答案是urlopen(url, timeout=123)。但如果是这样的话，为什么文档说[timeout, ]*，为什么不直接说timeout=None？

【问题讨论】：

标签： python-3.x parameter-passing documentation urllib

【解决方案1】：

这是独立功能的组合 - 方括号和星号。

[timeout, ] 表示timeout 是可选参数 - 为简化起见，您可以省略括号和括号内的所有内容 - 您将得到urllib.request.urlopen(url, data=None, *, cafile=None, capath=None, cadefault=False, context=None)。

* 表示以下所有参数都是仅关键字参数 - 您必须指定参数名称。

【讨论】：

不是所有的之前 *（url 除外）也是可选的和基于关键字的吗？
另外，为什么] 和* 之间没有逗号？
@falsePockets url 必须提供，data 和 timeout 是可选的，这三个都可以不提供参数名称，* 之后的所有参数都必须提供名称。我想可选参数和具有默认值的参数之间没有任何区别。差异仅存在于文档中，因为方括号仅存在于文档中。逗号在括号内，因为它应该与可选参数一起省略 - 我认为有点令人困惑，但基本上只是文档语法规则。

【解决方案2】：

看看实际的source 会很有帮助，上面写着：

def urlopen(url, data=None, timeout=socket._GLOBAL_DEFAULT_TIMEOUT,
            *, cafile=None, capath=None, cadefault=False, context=None):
// actual implementation

这实际上比文档更清楚。

【讨论】：

所以[timeout, ]*, 实际上与timeout=socket._GLOBAL_DEFAULT_TIMEOUT 相同？他们为什么不直接写呢？有什么区别？
@falsePockets：其实和timeout=socket._GLOBAL_DEFAULT_TIMEOUT, *是一样的。正如@Poolka 已经指出的那样，这似乎是纯粹的文档语法，并且不是有效的 Python 代码（尝试在文档中定义一个函数，解释器会将其标记为无效）。简而言之：区别在于一个是有效代码，另一个不是，他们可能认为文档语法可能更容易理解。这显然是值得商榷的。