标签: docstring

看来Python 2.7中的unittest模块已经改变了很多

我有一个测试用例：

class DemoTest(unittest.TestCase):
  def test_foo(self):
      """Test foo"""
      pass

控制台输出为：

测试 foo ... 好的

升级到 Python 2.7 后，控制台输出现在为：

test_foo (testcase.demotest.DemoTest)

测试 foo ... 好的

第一行描述是没有用的。我想隐藏它，但不知道如何隐藏。

是否可以使用 AST 解析模块级文档字符串？

我在这里使用 python 文档，访问模块令牌并获取文档不会产生模块级文档字符串。到目前为止，我不得不求助于导入模块并抓取它__doc__或使用inspect抓取文档。

我查看了pydoc 模块源以获取有关其他文档编写者如何解析文档字符串的线索，并发现 pydoc 最终必须与我的文档编写者做基本相同的事情才能获取模块级字符串。

我错过了什么吗？是通过实际导入模块来解析模块级文档字符串的唯一方法，还是可以直接从 AST 解析文档字符串？

紧跟在类或函数声明之后的 Python 文档字符串放置在__doc__属性中。

问题：如何提取函数中稍后出现的附加“内部”文档字符串？

更新：编译器会忽略此类文字语句。我可以通过 AST 找到他们（以及他们的线路号码）吗？

我为什么要问？

我有一个（尚未完全成熟的）想法，使用此类“内部”文档字符串来描述敏捷场景的给定/何时/然后部分：

def test_adding():
    """Scenario: Adding two numbers"""
    adder = Adder()
    """When I add 2 and 3"""
    result = adder.add(2, 3)
    """Then the result is 5"""
    assert result == 5

通过提取文档字符串，测试运行框架可以生成如下输出：

Scenario: Adding two numbers
   When I add 2 and 3 (PASS)
   Then the result is 5 (FAIL)

AssertionError   Traceback
...

我认为这比Behave、Freshen、Lettuce、PyCukes中采用的方法更简洁，这些方法需要为每个步骤定义一个单独的函数。我不喜欢必须将步骤文本作为函数名称重复 ( @When("I add numbers") def add_numbers())。但与普通的单元测试不同，文档字符串将添加打印出业务可读场景以供参考的功能。

为什么动态格式化文档字符串不起作用？在功能定义时有没有可接受的解决方法？

>>> DEFAULT_BAR = "moe's tavern"
>>> def foo(bar=DEFAULT_BAR):
...     """
...     hello this is the docstring
...     
...     Args:
...       bar (str)    the bar argument (default: {})
...     """.format(DEFAULT_BAR)
... 
>>> foo.__doc__
>>> foo.__doc__ is None
True

我尝试使用old-skool样式的%s格式,但也无法正常工作.

假设我有一个这样的类:

class TestCase(object):
    """Class docstring"""

    def meth(self):
        """Method docstring"""
        return 1

    @property
    def prop(self):
        """Property docstring"""
        return 2

对于我来说,获取类本身的文档字符串或常规方法很容易:

tc = TestCase()

print(tc.__doc__)
# Class docstring

print(tc.meth.__doc__)
# Method docstring

但是,这种方法不适用于属性 - 而是获取__doc__属性getter方法返回的任何对象的属性(在本例中int):

print(tc.prop.__doc__)
# int(x=0) -> int or long
# int(x, base=10) -> int or long
# ...

同样的事情适用于getattr(tc, "prop").__doc__和getattr(tc.prop, "__doc__").

我知道Python的内省机制能够访问我正在寻找的文档字符串.例如,当我打电话给help(tc)我时:

class TestCase(__builtin__.object)
 |  Class docstring
 |  
 |  Methods defined here:
 |  
 |  meth(self)
 |      Method docstring
 | …

我正在编写一个需要调用脚本的文档字符串的模块。到目前为止，我已经设法使用获取调用脚本的文件名

import inspect
filename = inspect.stack()[1].filename

文档字符串可以在调用脚本中使用__doc__. 然而，从被调用的脚本中获取文档字符串似乎并不简单。当然我可以写一个函数，但这必然会忽略一些不常见的情况。我有没有办法实际解析调用脚本以找到它的文档字符串（不执行它的代码）？

Julia 接受?sin命令行以显示帮助文本。我相信这样的帮助文本是作为文档字符串实现的。我想在运行时从我的 Julia 程序打印这样的文档字符串。怎么做？

我使用 mkdocs 和 mkdocstrings 插件来生成 Python 包的文档。

我的包裹以标准方式组织

- setup.py
- mkdocs.yaml
- docs/
- mypackage/
  - __init__.py
  - module1.py
  - module2.py
  - subpackage1/
     - __init__.py
     - submodule1.py
     - submodule2.py
- [...]

在mkdocs.yml：

plugins:
  - mkdocstrings
nav:
  - API: references.md

并在references.md：

# API references

::: mypackage

这不会生成任何文档（即“API”页面保持空白）

另一方面，这有效：

::: mypackage.module1

跑步mkdocs build -v：

DEBUG    -  mkdocstrings: Matched '::: mypackage'
DEBUG    -  mkdocstrings: Using handler 'python'
DEBUG    -  mkdocstrings: Collecting data
DEBUG    -  griffe: Found …

测试这样的代码的最佳方法是什么(下面的代码明显失败,而每次在不同的块中创建对象时):

def get_session(db_name, verbose, test):
"""Returns current DB session from SQLAlchemy pool.

>>> get_session('Mmusc20090126', False, True)
<sqlalchemy.orm.session.Session object at 0xfb5ff0>

"""
if test:
    engine = create_engine('sqlite:///:memory:', echo=verbose)
    log_load.debug('DB in RAM.')
else:
    engine = create_engine('sqlite:///' + 'DB/' + db_name + '.db', echo=verbose)
    log_load.debug('DB stored in file: %s' % 'DB/' + db_name + '.db')

# Create TABLES: Structures, Interactions, Interactors, PDB_UniProt, UniProtSeq
meta.create_all(engine)

Session = sessionmaker(bind=engine)
session = Session()

return session

假设我有一个功能,说:

>>> def foo(a):
        return a+1

我想为它写一个文档字符串.

在docstring中指定它需要a并返回+ 1的约定是什么？