logging** kwargs参数的正确方法是什么？
我使用sphinx和autodoc插件为我的Python模块生成API文档。 虽然我可以看到如何很好地logging特定的参数，但我找不到如何logging**kwargs参数的例子。
有没有人有一个清晰的方式来logging这些的好例子？
我认为subprocess进程模块的文档就是一个很好的例子。 为顶级/父级提供所有参数的详尽列表。 那么只需参考**kwargs所有其他出现的列表。
发现这个问题后，我决定下面这个有效的狮身人面像，而且工作得很好：
def some_function(first, second="two", **kwargs): r"""Fetches and returns this thing :param first: The first parameter :type first: ``int`` :param second: The second parameter :type second: ``str`` :param \**kwargs: See below :Keyword Arguments: * *extra* (``list``) -- Extra stuff * *supplement* (``dict``) -- Additional content """
r"""..."""是必需的，使这个“原始”文档string，从而保持\*完好（狮身人面像拾起作为文字*而不是“强调”的开始）。
所选的格式（带圆括号的types和m-dash分隔的描述的项目符号列表）仅仅是为了匹配由Sphinx提供的自动格式。
一旦你将“关键字参数”部分看作是默认的“参数”部分，看起来好像从一开始就可以更容易地展开自己的参数部分（根据其他一些答案） ，但是作为一个概念的certificate，如果你已经在使用狮身人面像，那么这是获得补充**kwargs的好方法之一。
Google Style文档由Sphinxparsing
免责声明：未经testing。
从狮身人面像文档string示例的这个剪贴画中 ， *args和**kwargs被展开：
def module_level_function(param1, param2=None, *args, **kwargs): """ ... Args: param1 (int): The first parameter. param2 (Optional[str]): The second parameter. Defaults to None. Second line of description should be indented. *args: Variable length argument list. **kwargs: Arbitrary keyword arguments.
我会build议以下解决scheme的紧凑性：
""" Args: param1 (int): The first parameter. param2 (Optional[str]): The second parameter. Defaults to None. Second line of description should be indented. *param3 (int): description *param4 (str): ... **key1 (int): description **key2 (int): description ...
请注意， **key参数不需要Optional 。
否则 ，您可以尝试显式地列出Keyword Args下的Other Parameters和**kwargs下的**kwargs Keyword Args （请参阅parsing的部分 ）：
""" Args: param1 (int): The first parameter. param2 (Optional[str]): The second parameter. Defaults to None. Second line of description should be indented. Other Parameters: param3 (int): description param4 (str): ... Keyword Args: key1 (int): description key2 (int): description ...
在他们的文档中有一个Sphinx的doctstring例子 。 具体来说，它们显示如下：
def public_fn_with_googley_docstring(name, state=None): """This function does something. Args: name (str): The name to use. Kwargs: state (bool): Current state to be in. Returns: int. The return code:: 0 -- Success! 1 -- No good. 2 -- Try again. Raises: AttributeError, KeyError A really great idea. A way you might use me is >>> print public_fn_with_googley_docstring(name='foo', state=None) 0 BTW, this always returns 0. **NEVER** use with :class:`MyPublicClass`. """ return 0
虽然你明确地询问了狮身人面像 ，但我也会指向Google Python风格指南 。 他们的文档示例似乎暗示他们不会专门调用kwargs。 （other_silly_variable =无）
def fetch_bigtable_rows(big_table, keys, other_silly_variable=None): """Fetches rows from a Bigtable. Retrieves rows pertaining to the given keys from the Table instance represented by big_table. Silly things may happen if other_silly_variable is not None. Args: big_table: An open Bigtable Table instance. keys: A sequence of strings representing the key of each table row to fetch. other_silly_variable: Another optional variable, that has a much longer name than the other args, and which does nothing. Returns: A dict mapping keys to the corresponding table row data fetched. Each row is represented as a tuple of strings. For example: {'Serak': ('Rigel VII', 'Preparer'), 'Zim': ('Irk', 'Invader'), 'Lrrr': ('Omicron Persei 8', 'Emperor')} If a key from the keys argument is missing from the dictionary, then that row was not found in the table. Raises: IOError: An error occurred accessing the bigtable.Table object. """ pass
ABB对于引用子stream程pipe理文件的答案有一个疑问。 如果您导入模块，则可以通过inspect.getsource快速查看模块文档。
python解释器使用Silent Ghost推荐的一个例子：
>>> import subprocess >>> import inspect >>> import print inspect.getsource(subprocess)
当然，您也可以通过帮助function查看模块文档。 例如help（subprocess）
我个人不是kwargs的子stream程文档string的粉丝，但是和Google的例子一样，它没有单独列出kwargs，如Sphinx文档示例所示。
def call(*popenargs, **kwargs): """Run command with arguments. Wait for command to complete, then return the returncode attribute. The arguments are the same as for the Popen constructor. Example: retcode = call(["ls", "-l"]) """ return Popen(*popenargs, **kwargs).wait()
我将这个答案包含在ABB的问题中，因为值得注意的是，您可以通过这种方式来查看任何模块的源代码或文档，以获得洞察力和灵感来评论您的代码。
如果其他人正在寻找一些有效的语法..这是一个示例docstring。 这就是我做的，我希望对你有用，但是我不能说它符合特别的要求。
def bar(x=True, y=False): """ Just some silly bar function. :Parameters: - `x` (`bool`) - dummy description for x - `y` (`string`) - dummy description for y :return: (`string`) concatenation of x and y. """ return str(x) + y def foo (a, b, **kwargs): """ Do foo on a, b and some other objects. :Parameters: - `a` (`int`) - A number. - `b` (`int`, `string`) - Another number, or maybe a string. - `\**kwargs` - remaining keyword arguments are passed to `bar` :return: Success :rtype: `bool` """ return len(str(a) + str(b) + bar(**kwargs)) > 20
这取决于你使用的文档风格，但是如果你使用numpydoc风格，build议使用Other Parameters来logging**kwargs 。
例如，按照夸诺尔的例子：
def some_function(first, second="two", **kwargs): """Fetches and returns this thing Parameters ---------- first : `int` The first parameter second : `str`, optional The second parameter Other Parameters ---------------- extra : `list`, optional Extra stuff. Default ``[]``. suplement : `dict`, optional Additional content. Default ``{'key' : 42}``. """
特别要注意的是，build议给予kwargs的默认值，因为这些从函数签名中是不明显的。
