首页
学习
活动
专区
圈层
工具
发布
首页
学习
活动
专区
圈层
工具
MCP广场
社区首页 >问答首页 >记录**kwargs参数的正确方法是什么?

记录**kwargs参数的正确方法是什么?
EN

Stack Overflow用户
提问于 2009-07-16 20:18:43
回答 8查看 51.8K关注 0票数 120

我正在使用Sphinxautodoc extension为我的Python模块生成API文档。虽然我可以看到如何很好地记录特定参数,但我找不到如何记录**kwargs参数的示例。

有没有人有一个很好的例子来记录这些?

EN

Stack Overflow用户

发布于 2014-01-11 08:30:50

在他们的文档中有一个Sphinx的doctstring example。具体地说,它们显示以下内容:

代码语言:javascript
复制
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

虽然您明确询问了sphinx,但我也会提到Google Python Style Guide。他们的文档字符串示例似乎暗示他们不会专门调用kwargs。(other_silly_variable=None)

代码语言:javascript
复制
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

A-B-B有一个关于参考子流程管理文档的公认答案的问题。如果您导入模块,您可以通过inspect.getsource快速查看模块文档字符串。

python解释器使用Silent Ghost建议的示例:

代码语言:javascript
复制
>>> import subprocess
>>> import inspect
>>> import print inspect.getsource(subprocess)

当然,您也可以通过help函数查看模块文档。例如help(子进程)

我个人并不喜欢以kwargs为例的子进程docstring,但像Google示例一样,它没有像Sphinx文档示例中所示的那样单独列出kwargs。

代码语言:javascript
复制
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()

我将这个答案包含在A-B-B的问题中,因为值得注意的是,您可以通过这种方式查看任何模块的源代码或文档,以获得对代码进行注释的见解和灵感。

票数 13
EN
查看全部 8 条回答
页面原文内容由Stack Overflow提供。腾讯云小微IT领域专用引擎提供翻译支持
原文链接:

https://stackoverflow.com/questions/1137161

复制
相关文章

相似问题

领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档