标签: docstring

我正在尝试决定在类docstring中放入什么信息以及在__init__方法docstring中放入什么.到目前为止,我已经在类docstring中概述了类以及如何使用它,而与初始化(参数详细信息等)直接相关的东西我放在__init__docstring中.

今天我开始想知道这是否是正确的做法,所以我看了几个内置模块,我发现该__init__方法几乎从来没有文档字符串.根据PEP8,"非公开方法不需要Docstrings",但是不 __init__公开？

同样,那些其他特殊方法,比如__getitem__,__getattr__或者__new__,他们应该有文档字符串吗？或者我应该只提一下他们在类docstring中的后果？

我想强制Eclipse在弹出窗口中显示Python的帮助输出,而不是整个函数,即给出:

def myFunc(arg):
    '''Function description'''
    return 1

我希望代码辅助弹出窗口只包含"功能描述"而不是"返回1"

假设我有以下代码:

def foo(s):
    """A dummy function foo. For example:

>>> a = '''This is a test string line 1
This is a test string line 2
This is a test string line 3'''
>>> foo(a)
This is a test string line 1
This is a test string line 2
This is a test string line 3
>>>
    """
    print s

if __name__ == '__main__':
    import doctest
    doctest.testmod()

让我们把它保存为foo.py. 当我跑:

C:\Python27>python.exe foo.py
**********************************************************************
File "foo.py", line 5, in __main__.foo
Failed example: …

这个问题似乎在StackOverflow和其他地方经常出现,但我无法在任何地方找到一个完全令人满意的解决方案.

似乎有两种类型的常见解决方案.第一个(例如http://article.gmane.org/gmane.comp.python.general/630549)使用函数装饰器:

class SuperClass:
    def my_method(self):
        '''Has a docstring'''
        pass

class MyClass(SuperClass):
    @copy_docstring_from(SuperClass)
    def my_method(self):
        pass

assert SuperClass.my_method.__doc__ == MyClass.my_method._doc__

这可能是最简单的方法,但它需要至少重复一次父类名称,如果在直接祖先中找不到docstring,它也会变得更加复杂.

第二种方法使用元类或类装饰器(参见Python中的继承方法'docstrings,将父类docstring继承为__doc__属性,http ://mail.python.org/pipermail/python-list/2011-June/606043 . html),看起来像这样:

class MyClass1(SuperClass, metaclass=MagicHappeningHere):
    def method(self):
        pass

# or 

@frobnicate_docstrings
class MyClass2(SuperClass):
    def method(self):
        pass

assert SuperClass.my_method.__doc__ == MyClass1.my_method._doc__
assert SuperClass.my_method.__doc__ == MyClass2.my_method._doc__

但是,使用此方法,docstring仅在创建类后设置,因此装饰器无法访问,因此以下操作无效:

def log_docstring(fn):
    print('docstring for %s is %s' % (fn.__name__, fn.__doc__)
    return fn

class MyClass(SuperClass, metaclass=MagicHappeningHere):
# or
#@frobnicate_docstrings
#class MyClass2(SuperClass): 
    @log_docstring
    def method(self):
        pass …

我有一个python文件,其原始字符串作为docstrings.

def a():
    '\n\tthis\n\tis\n\tthe docstring.\n\t'
    print 'hello world'

我如何重写docstring看起来像

def a():
    """
    this
    is
    the docstring.
    """
    print 'hello world'

PyCharm,当我开始在docstring中输入时,Python IDE会为docstring生成一个模板.这是为简单函数生成的模板.

def add_them(x, y):
    """

    :param x: 
    :param y: 
    :return:
    """
    z = x + y
    return z

我没有发现它类似于Python的官方文档字符串约定.

此模板是否与readthedocs等任何文档生成器一起使用？

有人如何有效使用？

填写模板的正确方法是什么？

谢谢.

多行功能或协议文档字符串可以轻松格式化:

(defn foo
  "Does a very complicated thing that I need to explain in excruciating detail.
  Firstly, this function stringifies x with the standard greeting of 'Hello'.
  Secondly, it appends the necessary exclamation point to the resulting string.
  Finally, it prints the resulting result to *out*, followed by a newline and
  the appropriate flush."
  [x]
  (println (str "Hello, " x "!")))

(defprotocol Bar
  "A retail business establishment that serves alcoholic beverages, such as
  beer, wine, liquor, cocktails, and other beverages …

我想解析一个numpydoc docstring并以编程方式访问每个组件.

例如:

def foobar(a, b):
   '''Something something

   Parameters
   ----------
   a : int, default: 5
        Does something cool
   b : str
        Wow
'''

我想做的是:

parsed = magic_parser(foobar)
parsed.text  # Something something
parsed.a.text  # Does something cool
parsed.a.type  # int
parsed.a.default  # 5

我一直在寻找像numpydoc和拿破仑这样的东西但我没有找到任何好的线索如何在我自己的程序中使用它们.我很感激任何帮助.

我想使用Google风格的docstrings for Python.我已指定Pycharm应该期待Google文档字符串:

出于某种原因,PyCharm不会在工具提示中显示我的文档字符串:

我在这里引用了适当的Google docstring格式示例:http://www.sphinx-doc.org/en/stable/ext/example_google.html

我不清楚为什么PyCharm没有显示我的文档字符串.

我知道这可以被视为基于意见的,但谷歌搜索并没有找到我希望的资源,我正在寻找Python社区中任何既定和商定的最佳实践的链接.

我是一个组织中的中级Python程序员,他曾用各种语言编写混淆代码的历史非常糟糕.我真的想树立好的编程风格和实践的例子.为此,我正在关注PEP 8,在我写的所有内容上运行pylint,并深入思考每个建议,而不是简单地解雇它们.我将更长,更复杂的方法分解为更短的方法,部分原因在于它的建议.我还按照这种风格写了详细的文档字符串:http://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html

对我来说,一个挑战是,虽然我不是我组织中唯一的Python程序员,但我似乎是唯一一个认真对待这些内容的人,而我的同事似乎并不介意无证件,重复的代码,并命名为例如,不遵循任何特定模式.所以我不认为让他们审查我的代码或从他们那里学习是我最好的选择.

我刚从pylint得到了我的第一个"模块中的太多行"消息.我没有写完模块 - 我想在现有的类中添加至少一个类和几个方法.我知道这个想法是模块应该"做一件事",但"事物"还没有完全实现.

以下是pylint给我的一些统计数据:

+---------+-------+-----------+-----------+------------+---------+
|type     |number |old number |difference |%documented |%badname |
+=========+=======+===========+===========+============+=========+
|module   |1      |1          |=          |100.00      |0.00     |
+---------+-------+-----------+-----------+------------+---------+
|class    |3      |3          |=          |100.00      |0.00     |
+---------+-------+-----------+-----------+------------+---------+
|method   |27     |27         |=          |100.00      |0.00     |
+---------+-------+-----------+-----------+------------+---------+
|function |2      |2          |=          |100.00      |0.00     |
+---------+-------+-----------+-----------+------------+---------+

+----------+-------+------+---------+-----------+
|type      |number |%     |previous |difference |
+==========+=======+======+=========+===========+
|code      |266    |24.98 |266      |=          |
+----------+-------+------+---------+-----------+
|docstring |747    |70.14 |747      |=          |
+----------+-------+------+---------+-----------+
|comment   |41     |3.85  |41       |= …