问题标签 [docstring]

I have seen a few different styles of writing docstrings in Python, what are the most popular styles?

我有具有对象属性的 Python 类，这些对象属性仅在运行构造函数时声明，如下所示：

如果我现在使用help(Foo)或尝试Foo在 Sphinx 中记录，则不会显示self.basepathandself.availableruns属性。这对我们 API 的用户来说是个问题。

我尝试寻找一种标准方法来确保解析器可以找到这些“动态声明的”属性（最好是文档字符串），但到目前为止还没有运气。有什么建议么？谢谢。

I have a wrapper function that returns a function. Is there a way to programmatically set the docstring of the returned function? If I could write to __doc__ I'd do the following:

Then I could do

However, since __doc__ is read-only, I can't do that. What's the correct way?

Edit: Ok, I wanted to keep this simple, but of course this is not what I'm actually trying to do. Even though in general __doc__ is writeable in my case it isn't.

I am trying to create testcases for unittest automatically. I have a wrapper function that creates a class object that is a subclass of unittest.TestCase:

If I create this class and try to set the docstring of testSomething I get an error:

假设我有一个函数，比如说：

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

在文档字符串中指定它接受 a 并返回 a+1 的约定是什么？

在 PHP 中，我习惯了 PHPdoc 语法：

— 一个简短的有用参考：当您只需要回忆“那是什么？？”时非常方便，尤其是对于 3rd 方库。此外，所有 IDE 都可以在弹出提示中显示此内容。

Python 中似乎没有约定：只是纯文本。它很好地描述了事情，但它太长了，无法作为摘要。

好吧，就这样吧。但在我的应用程序中，我不想使用成堆的明文。

是否有任何众所周知的约定可以遵循？以及如何记录类属性？！PyCharm IDE食谱特别受欢迎 :)

在 Python3 中有一个用于功能注释的PEP 3107 。这对 2.x（特别是 2.6）没有用

还有一个用于 reStructuredText 的PEP 0287：花哨但仍然没有结构化。

我正在开发一个具有许多小功能但其文档字符串往往很长的模块。文档字符串使模块的工作变得烦人，因为我必须不断地滚动一个长文档字符串才能找到一点实际代码。

有没有办法将文档字符串与它们记录的函数分开？我真的希望能够在远离代码的文件末尾指定文档字符串，或者更好的是，在单独的文件中。

我刚刚开始学习 Python 并使用 Emacs 作为我的编辑器。目前，Emacs 对普通字符串（单引号）和文档字符串（三引号）使用相同的颜色。我希望文档字符串是不同的颜色，所以我使用“选项->自定义 Emacs”菜单选项将“font-lock-doc-face”更改为新颜色并保存更改。然而，Emacs 继续保持文档字符串与普通字符串相同的颜色。更改普通字符串的颜色也会将更改应用于文档字符串。

似乎 Emacs 将文档字符串和普通字符串视为相同。有没有办法让 Emacs 与普通字符串分开正确地查找和着色 Python 文档字符串？

编辑：我正在使用具有默认 Python 模式设置的 Emacs 23.1.1（Kubuntu 10.10 包）。我还将 color-theme 包与午夜主题一起使用。

似乎在 Python 2.7 中 unittest 模块发生了很大变化

我有一个测试用例：

控制台输出为：

测试 foo ... 好的

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

test_foo (testcase.demotest.DemoTest)

测试 foo ... 好的

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

我在工作中使用 Flask 为内部应用程序编写 Web 服务。许多 Web 服务 URI 的返回 HTML 部分，我试图找出一种干净的方式来存储 html 模板字符串。我不想将模板字符串放在单独的文件中，因为它们通常只有几行长，而且我不希望有 20 个模板文件，每个文件都有 3 行。我正在考虑在函数的文档字符串中定义一个函数的 html 模板字符串，因为我觉得这将有多种用途。它将作为文档，基本上说“这是我输出的”，并且让我不必将 3 行模板字符串存储在单独的文件中。这就是我所说的：

我不知道这是否会成为一场噩梦……有什么想法吗？

我目前是从 Python 开始的，我有很强的 PHP 背景，在 PHP 中我已经养成了将javadoc其用作文档模板的习惯。

我想知道它是否在 Python 中javadoc作为文档。这里的既定惯例和/或官方准则是什么？docstring

例如，像这样的东西过于复杂，不适合 Python 的思维方式，还是我应该尽量简洁？

如果我有点太详尽了，我应该改用这样的东西吗（大多数文档都没有通过该__doc__方法打印出来）？