Python doc参数语法的说明

Posted 2021-05-04

是否有人能够帮助我理解传递给Python文档中某些方法的参数的语法？

令我困惑的事物类型的例子来自iter（）函数

iter(o[, sentinel])

根据我的理解，这相当于

iter(o, sentinel)

但至于为什么我真的不明白。

答案

function(mandatory_argument[, optional_argument]表示一个可选参数，如果提供，它将改变函数。在iter() documentation：

根据第二个参数的存在，第一个参数的解释非常不同。

以什么方式可选参数改变函数应该在文档中描述。

可选参数可以嵌套，因此您可能会看到类似（source）的内容：

bytearray([source[, encoding[, errors]]])

这意味着每个参数都是可选的，但是建立在之前的参数上。所以以下都是有效的调用：

bytearray(source)
bytearray(source, encoding)
bytearray(source, encoding, errors)

但这不是：

bytearray(source, errors=errors)

还有第二种方法来指示参数是可选的：

__import__(name, globals=None, locals=None, fromlist=(), level=0)

这告诉我们所有这些参数（但名称）都是可选的，并告诉我们何时不为它们提供参数的默认值。

在纯python的代码站点上，您可以通过以下方式获取可选参数：

def iter(o, sentinel=None):
    [do something]

但是这不会以上面的方式记录，正如我们在__import__的例子中所看到的：

__import__(name, globals=None, locals=None, fromlist=(), level=0)

要了解为什么iter不同，请阅读我帖子末尾的部分。

另请注意，在iter()内置的示例中，您不能将sentinel作为关键字参数提供，并且尝试将引发TypeError：

>>> iter([], sentinel=None)
Traceback (most recent call last):
   File '<stdin>', line1, in <module>
TypeError: iter() takes no keyword arguments

在其他情况下，尽管有可能：

>>> bytearray('', encoding='UTF-8')
bytearray(b'')

如果没有先前的参数提供后来的参数将会引发错误，这仍然是事实。

>>> bytearray('', errors='')
Traceback (most recent call last):
  File '<stdin>', line 1, in <module>
TypeError: string argument without an encoding

“像语法一样的关键字”是在python中记录可选参数的“常规”方式。为什么iter与众不同？ iter是内置的，并没有在python中实现，而是在C中。如果我们查看它的source code，我们看到它将参数视为可能有一个或两个参数的元组。

builtin_iter(PyObject *self, PyObject *args)
{
    PyObject *v, *w = NULL;

    if (!PyArg_UnpackTuple(args, "iter", 1, 2, &v, &w))
        return NULL;
    if (w == NULL)
        return PyObject_GetIter(v);
    if (!PyCallable_Check(v)) {
        PyErr_SetString(PyExc_TypeError,
                "iter(v, w): v must be callable");
        return NULL;
    }
    return PyCallIter_New(v, w);
}

这可能解释了“类似列表的语法”。似乎[optional_argument]表示法仅用于在C中编程的模块。对于普通用户，如果有的话，它没有任何区别

function([optional_argument])

要么

function(optional_argument=True)

另一答案

括号表示有问题的参数是可选的。

iter(o[, sentinel])

即上面的例子意味着iter是一个函数，它接受一个强制参数o和一个可选参数sentinel。

这意味着您可以像这样调用此函数：

iter(o)  # Method 1

或者像这样：

iter(o, sentinel)  # Method 2

根据您使用方法1或2的函数的行为由文档中的文本描述：

返回一个迭代器对象。根据第二个参数的存在，第一个参数的解释非常不同。如果没有第二个参数，o必须是支持迭代协议（iter（）方法）的集合对象，或者它必须支持序列协议（getitem（）方法，其整数参数从0开始）。如果它不支持这些协议中的任何一个，则引发TypeError。如果给出第二个参数sentinel，则o必须是可调用对象。在这种情况下创建的迭代器将为每个对next（）方法的调用调用o而不带参数;如果返回的值等于sentinel，则会引发StopIteration，否则返回该值。