Tag: docstring

我如何以编程方式设置文档string？: 我有一个包装函数返回一个函数。有没有一种方法来编程设置返回的函数的文档string？如果我可以写入__doc__我会做以下几点： def wrapper(a): def add_something(b): return a + b add_something.__doc__ = 'Adds ' + str(a) + ' to `b`' return add_something 然后我可以做 >>> add_three = wrapper(3) >>> add_three.__doc__ 'Adds 3 to `b` 但是，由于__doc__是只读的，我不能这样做。什么是正确的方法？编辑：好吧，我想保持这个简单，但当然这不是我实际上想要做的。即使通常__doc__在我的情况下是可写的，但它不是。我正在尝试为unittest自动创buildtesting用例。我有一个包装函数，它创build一个类unittest.TestCase的子类的类对象： import unittest def makeTestCase(filename, my_func): class ATest(unittest.TestCase): def testSomething(self): # Running test in here with […]

Python装饰器处理文档: 使用docstrings与装饰器有问题。给出以下示例： def decorator(f): def _decorator(): print 'decorator active' f() return _decorator @decorator def foo(): '''the magic foo function''' print 'this is function foo' help(foo) 现在的帮助并没有像预期的那样给我显示foo的文档，它显示： Help on function _decorator in module __main__: _decorator() 没有装饰者，帮助是正确的： Help on function foo in module __main__: foo() the magic foo function 我知道，函数foo是由装饰器包装的，所以函数对象不再是函数foo了。但是，如何获得文档string（和帮助）是一个很好的解决scheme？

如何在执行时打印Python文件的文档string？: 我有一个文档string的Python脚本。当命令行参数的parsing不成功时，我想打印用户信息的文档string。有没有办法做到这一点？最小的例子 #!/usr/bin/env python """ Usage: script.py This describes the script. """ import sys if len(sys.argv) < 2: print("<here comes the docstring>")

有没有真正的替代Python文档的reStructuredText？: 我很快就开始了一个开源的Python项目，并且正在尝试提前决定如何编写我的文档。显而易见的答案是将reStructuredText和Sphinx与autodoc结合使用，因为我非常喜欢简单地在我的文档中恰当地logging我的代码的想法，然后让Sphinx自动为我构build一个API文档。问题是它使用的reStructuredText语法 – 我认为它在呈现之前是完全不可读的。例如：：param path：要包装的文件的path ：inputpath：str ：param field_storage：要包装的：class：`FileStorage`实例：inputfield_storage：FileStorage ：param temporary：是否在File实例中删除文件被破坏：inputtemporary：bool 你必须真的放慢速度，花一点时间去理解这种句法混乱。我更喜欢谷歌的方式（谷歌Python风格指南），与上述相对应的是这样的： ARGS： path（str）：要包装的文件的path field_storage（FileStorage）：要包装的FileStorage实例临时（bool）：文件是否删除时的文件实例被破坏更好！但是，当然，狮身人面像将不会有这样的东西，并且在“长矛”之后把所有的文字都排成一列。所以总结一下 – 在我用这个reStructuredText语法去玷污我的代码库之前，我想知道是否有任何真正的替代方法来使用它和Sphinx，而不仅仅是编写我自己的API文档。例如，是否有一个处理Google Style Guide文档string样式的Sphinx扩展？

在Python中inheritance方法的文档: 我有一个面向对象的层次结构，它的代码本身需要尽可能多的维护。例如， class Swallow(object): def airspeed(self): """Returns the airspeed (unladen)""" raise NotImplementedError class AfricanSwallow(Swallow): def airspeed(self): # whatever 现在，问题是AfricanSwallow.airspeed不会inheritance超类方法的文档string。我知道我可以使用模板方法模式，即保持文档string class Swallow(object): def airspeed(self): """Returns the airspeed (unladen)""" return self._ask_arthur() 并在每个子类中实现_ask_arthur 。但是，我想知道是否有另一种方式来让文档被inheritance，也许还有一些我还没有发现的装饰器呢？

自定义PyCharm文档string存根（即谷歌docstring或numpydoc格式）: PyCharm 2.7（或者PyCharm 3）是否支持自定义文档string和doctest存根？如果是这样，那么怎么去写这个特定types的自定义扩展？我目前的项目已经使用Google Python风格指南（ http://google-styleguide.googlecode.com/svn/trunk/pyguide.html ）进行了标准化。我喜欢PyCharm的文档string支持，但现在只有两种支持的格式是epytext和reStructureText。我想要，并愿意自己写一个PyCharm插件，它创build一个格式为Google或Numpydoc风格的文档注释存根（ https://pypi.python.org/pypi/sphinxcontrib-napoleon/ ）。这里特别重要的是将PyCharm与其他两种文档types的types推断能力结合起来。

将文档添加到namedtuples？: 是否有可能以简单的方式添加一个文档string到一个namedtuple？我试过了 from collections import namedtuple Point = namedtuple("Point", ["x", "y"]) """ A point in 2D space """ # Yet another test """ A(nother) point in 2D space """ Point2 = namedtuple("Point2", ["x", "y"]) print Point.__doc__ # -> "Point(x, y)" print Point2.__doc__ # -> "Point2(x, y)" 但是这并没有削减。有可能以其他方式做？

我可以使用doxygen编写Python代码吗（这是否合理）？: 我喜欢doxygen来创buildC或PHP代码的文档。我有一个即将到来的Python项目，我想我记得Python没有/ * .. * /注释，也有自己的自我文档设施，这似乎是Python文档的方式。我可以只使用doxygen吗？有什么特别需要注意的？我已经在Python中做了一些编码，但到目前为止，只在我懒得logging的小项目上（是的，我知道…但现在我们假装没问题）。

如何在Python中logging类的属性？: 我正在编写一个轻量级类，其属性旨在公开访问，并且有时仅在特定的实例化中被覆盖。 Python语言中没有规定为类属性或任何属性创build文档string。如果有的话，什么是公认的方式来logging这些属性？目前我正在做这样的事情： class Albatross(object): """A bird with a flight speed exceeding that of an unladen swallow. Attributes: """ flight_speed = 691 __doc__ += """ flight_speed (691) The maximum speed that such a bird can attain. """ nesting_grounds = "Raymond Luxury-Yacht" __doc__ += """ nesting_grounds ("Raymond Luxury-Yacht") The locale where these birds congregate to […]

使用javadoc的Python文档: 我现在开始使用Python，我有一个强大的PHP背景，在PHP中，我习惯于使用javadoc作为文档模板。我想知道如果javadoc在Python中作为docstring文档的地方。像这样的东西太复杂了，以适应Python的思维方式，还是应该尽可能简洁？ """ replaces template place holder with values @param string timestamp formatted date to display @param string priority priority number @param string priority_name priority name @param string message message to display @return string formatted string """ 如果我有点太详尽，我应该去这样的事情（而大多数的文档不通过__doc__方法打印）？ # replaces template place holder with values # # @param string timestamp formatted date to display […]