我想使用 Python 文档字符串来更好地记录我的代码。
在下面的函数中,它将一个列表作为输入并将文件写入磁盘。我想知道如何将文档字符串中函数的输出记录为 None 中的函数返回类型。它有约定吗?
def foo(list_of_items: list) -> None :
"""Simple function.
Parameters
----------
list_of_items : list of str
list of some texts
Returns
-------
what is the best way to write this section?
"""
file = open('/path/output.txt')
file.write(list_of_items[1])
file.close()
Run Code Online (Sandbox Code Playgroud) 我正在为带有clear_stop_character函数的python包编写文档,其中用户可以在列表中提供额外的停止字符。在我写的文档中:
"""
stoplist (list, default empty): Accepts a list of extra stop characters,
should escape special regex characters (e.g., stoplist=['\\*']).
"""
Run Code Online (Sandbox Code Playgroud)
对于用户来说,看到停止字符之前的双反斜杠至关重要。然而,help()构建包的结果显示:
"""
stoplist (list, default empty): Accepts a list of extra stop characters,
should escape special regex characters (e.g., stoplist=['\*']).
"""
Run Code Online (Sandbox Code Playgroud)
所以,这会对用户产生误导。
顺便说一句,我没有根据之前的问题找到解决方案。
有任何想法吗?
我不知道如何为Raises. 见下文。有可能吗?我得到的是一个要点RuntimeError(同样适用于ValueError)。\n例如:
Raises: \xe2\x80\xa2 RuntimeError -\n \xe2\x97\xa6 case1: when x happens * case 2: when y happens\n \xe2\x80\xa2 ValueError -\n \xe2\x97\xa6 a is not all lowercase * current day is Sunday\nRun Code Online (Sandbox Code Playgroud)\nclass A\n def f1(self, a: str):\n """f1\n\n Parameters\n ----------\n a: str\n a\n\n Raises\n ------\n RuntimeError\n * case 1: when x happens\n * case 2: when y happens\n\n ValueError\n * ``a`` is not all lowercase\n * current day is Sunday\n """\nRun Code Online (Sandbox Code Playgroud)\n 在 python 模块中,在模块的文档字符串中我有以下内容:
\n:meth:`my_method`\nRun Code Online (Sandbox Code Playgroud)\n我在当前模块中有以下课程:
\nclass GameP:\n\n ...\n\n def my_method(self):\n return f"{self._name} {self.selected}"\nRun Code Online (Sandbox Code Playgroud)\nSphinx 不会为此创建链接,但在 Sphinx 文档中我们有:
\n\n\n通常,首先搜索这些角色中的名称,无需任何进一步的限定,然后在前面加上当前模块名称,然后在前面加上当前模块和类名称(如果有)。如果在名称前添加点,则此顺序相反。例如,在 Python\xe2\x80\x99s codecs127 模块的文档中,:py:func:
\nopen始终指内置函数,而 :py:func:.open指 codecs.open()。
为什么粗体部分不适合我?:meth:角色没有为我建立链接。
我正在寻找一种工具,可以将函数中已添加的类型注释添加到 PyCharm 生成的文档字符串中。
我已经在 JetBrains 上关注这个问题很长时间了,但这个问题似乎还没有取得任何进展。
我也看到了这篇文章,但它似乎太具体了,只适用于谷歌文档字符串。
我已经在 PyPI 上查看了这个包,但这与我需要的相反。我需要的是将参数中提供的类型提示添加到文档字符串中,而不是相反。
这可能与如何使 PyCharm 从函数定义中获取类型提示并在文档字符串中填充类型值有关?,但我只需要一个通用的解决方案,或者至少一个可以与 Numpy docstring 或 reStructuredText 配合使用并且可以与 PyCharm 很好地配合的解决方案。
我只是看到自己回来研究这个东西,希望能得到一些东西,但找不到我需要的东西。什么工具可以用于此目的?
我对类型提示和文档字符串的使用感到困惑。它们不是重复的信息吗?
例如:
def my_func(name: str):
"""
print a name.
Parameters
----------
name : str
a given name
"""
print(name)
Run Code Online (Sandbox Code Playgroud)
信息不是name: str给出了两次吗?
我正在为一个包开发文档,当我构建 sphinx 文档时,我得到了双冒号

对于每个函数定义的所有字段。
我的文档字符串使用 numpydoc 样式,这些文档中没有冒号来指示它们可能来自哪里:
"""
Function description
Parameters
-----------
param1: str or list
A description for the parameter
Returns
-----------
Dictionary
Some info about what is returned
Examples
-----------
>>> output = somefunction(param1)
"""
Run Code Online (Sandbox Code Playgroud)
以前有人遇到过这个吗?值得注意的是,这种情况不会发生在Examples现场。只是Parameters,,Returns和Return Type。
正如本文所述,即使 napoleon 将字段添加为文档,autodoc 也会急切地将类变量添加到文档中:
from dataclasses import dataclass
@dataclass
class Foo():
"""Some class
Attributes:
a: foo
b: bar
"""
a: str
b: int
def c(self) -> int:
"""Here's a doc'd function
"""
return 3
Run Code Online (Sandbox Code Playgroud)
我想明确告诉 autodoc 不要记录任何类变量(在数据类的情况下也是实例变量) - 我只希望 autodoc 显示给定类的声明函数并让 napoleon 处理它的所有类的类/实例变量发现. 这是否可以在没有:exclude-members:每堂课的情况下实现(这是一个巨大的麻烦)?
我已经尝试过:
autodoc_default_options = {
'members': True,
'undoc-members': False,
}
Run Code Online (Sandbox Code Playgroud)
在我的conf.py文件中.rst:
.. automodule:: some.module
:members:
:show-inheritance:
Run Code Online (Sandbox Code Playgroud)
这应该隐藏无证成员,但他们仍然出现:
如下图所示,_S@map和是什么_T@map意思?
附加信息:
查看multiprocessing.Pool.map定义,没有类型提示,因此上面的类型必须由 Pylance 自动生成,Pylance 是我使用的语言服务器
def map(self, func, iterable, chunksize=None):
'''
Apply `func` to each element in `iterable`, collecting the results
in a list that is returned.
'''
return self._map_async(func, iterable, mapstar, chunksize).get()
Run Code Online (Sandbox Code Playgroud) 我的班上有一些方法,只能供该班的其他方法使用。我已经给他们的名字加上了“ _”。我可以对epydoc隐藏这些功能吗?这是个好主意吗?
我应该使用“ _”还是双下划线?老实说,在某些地方阅读了它们之后,我没有发现任何不同。是否应仅在模块/类(实例)函数上使用此命名约定?还是变量?
docstring ×10
python ×9
type-hinting ×2
autodoc ×1
bulletedlist ×1
epydoc ×1
escaping ×1
numpydoc ×1
private ×1
pycharm ×1
pylance ×1
python-3.x ×1