标签: docstring

如何在Python中为返回None但在磁盘中写入文件的函数编写文档字符串?

我想使用 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)

python docstring

5
推荐指数
1
解决办法
3558
查看次数

在 python 文档字符串中编写双反斜杠

我正在为带有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)

所以,这会对用户产生误导。
顺便说一句,我没有根据之前的问题找到解决方案。
有任何想法吗?

python documentation docstring escaping

5
推荐指数
1
解决办法
1201
查看次数

如何在文档字符串中添加“Raises”的项目符号列表?

我不知道如何为Raises. 见下文。有可能吗?我得到的是一个要点RuntimeError(同样适用于ValueError)。\n例如:

\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\n
Run Code Online (Sandbox Code Playgroud)\n
class 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        """\n
Run Code Online (Sandbox Code Playgroud)\n

python docstring bulletedlist python-sphinx

5
推荐指数
0
解决办法
617
查看次数

Sphinx meth角色不创建链接

在 python 模块中,在模块的文档字符串中我有以下内容:

\n
:meth:`my_method`\n
Run Code Online (Sandbox Code Playgroud)\n

我在当前模块中有以下课程:

\n
class GameP:\n\n    ...\n\n    def my_method(self):\n        return f"{self._name} {self.selected}"\n
Run Code Online (Sandbox Code Playgroud)\n

Sphinx 不会为此创建链接,但在 Sphinx 文档中我们有:

\n
\n

通常,首先搜索这些角色中的名称,无需任何进一步的限定,然后在前面加上当前模块名称,然后在前面加上当前模块和类名称(如果有)。如果在名称前添加点,则此顺序相反。例如,在 Python\xe2\x80\x99s codecs127 模块的文档中,:py:func:open始终指内置函数,而 :py:func:.open指 codecs.open()。

\n
\n

为什么粗体部分不适合我?:meth:角色没有为我建立链接。

\n

python docstring cross-reference python-sphinx

5
推荐指数
1
解决办法
570
查看次数

python 自动在文档字符串中添加类型提示

我正在寻找一种工具,可以将函数中已添加的类型注释添加到 PyCharm 生成的文档字符串中。

我已经在 J​​etBrains 上关注这个问题很长时间了,但这个问题似乎还没有取得任何进展。

我也看到了这篇文章,但它似乎太具体了,只适用于谷歌文档字符串。

我已经在 PyPI 上查看了这个包,但这与我需要的相反。我需要的是将参数中提供的类型提示添加到文档字符串中,而不是相反。

这可能与如何使 PyCharm 从函数定义中获取类型提示并在文档字符串中填充类型值有关?,但我只需要一个通用的解决方案,或者至少一个可以与 Numpy docstring 或 reStructuredText 配合使用并且可以与 PyCharm 很好地配合的解决方案。

我只是看到自己回来研究这个东西,希望能得到一些东西,但找不到我需要的东西。什么工具可以用于此目的?

docstring type-hinting pycharm python-3.x python-typing

5
推荐指数
1
解决办法
2230
查看次数

打字和文档字符串中存在重复信息?

我对类型提示和文档字符串的使用感到困惑。它们不是重复的信息吗?

例如:

def my_func(name: str):
    """
    print a name.
    
    Parameters
    ----------
    name : str
       a given name
    """
    print(name)
Run Code Online (Sandbox Code Playgroud)

信息不是name: str给出了两次吗?

python docstring type-hinting python-typing

5
推荐指数
1
解决办法
1266
查看次数

Sphinx 文档显示字段中的双冒号

我正在为一个包开发文档,当我构建 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。

python docstring python-sphinx numpydoc

5
推荐指数
1
解决办法
643
查看次数

Sphinx 从 autodoc 中删除数据类字段

正如本文所述,即使 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)

这应该隐藏无证成员,但他们仍然出现:

在此输入图像描述

python docstring python-sphinx autodoc sphinx-napoleon

5
推荐指数
1
解决办法
1286
查看次数

Python 类型提示中的符号 @ 是什么意思?

如下图所示,_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)

python docstring visual-studio-code pylance

5
推荐指数
0
解决办法
404
查看次数

epydoc隐藏一些类函数吗?

我的班上有一些方法,只能供该班的其他方法使用。我已经给他们的名字加上了“ _”。我可以对epydoc隐藏这些功能吗?这是个好主意吗?

我应该使用“ _”还是双下划线?老实说,在某些地方阅读了它们之后,我没有发现任何不同。是否应仅在模块/类(实例)函数上使用此命名约定?还是变量?

python docstring private epydoc

4
推荐指数
1
解决办法
1115
查看次数