标签: docstring

因此,我正在查看一些代码,并在pylint的帮助下将其提升到PEP 8标准,我注意到如果我使用三重引号用于打印语句,其中文本超过120个字符(我们允许120而不是79)pylint没抱怨.
这是pylint中的一个错误还是它认为它可能是一个注释,并且对行的长度更宽松,或者它不关心你在三重引号中使用字符串有多远,因为你可能想要那样格式化它们？

为清楚起见:是的,在任何超过线路长度的情况下,pylint通常都能正常工作.

我想使用sphinx构建我们的文档,并获得与NumPy文档相同的参数格式(https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt)

我发现有两种方法可以用sphinx记录第一种样式的参数,其中一种是

:param name: description

要么

:keyword name: description

和另一个(这是NumPy风格)

Parameters
----------
name: type
    description

以下是一个示例:

http://docs.scipy.org/doc/numpy/reference/distutils.html#module-numpy.distutils

和来源

def get_subpackage(self,subpackage_name,
                   subpackage_path=None,
                   parent_name=None,
                   caller_level = 1):
    """Return list of subpackage configurations.

    Parameters
    ----------
    subpackage_name: str,None
        Name of the subpackage to get the configuration. '*' in
        subpackage_name is handled as a wildcard.
    subpackage_path: str
        If None, then the path is assumed to be the local path plus the
        subpackage_name. If a setup.py file is not found in the
        subpackage_path, then …

我使用描述符来定义接口类的寄存器:

class Register(object):
    def __init__(self, address, docstring="instance docstring"):
        self.address = address    
        self.__doc__ = docstring

    def __get__(self, obj, objtype):
        return obj.read(self.address)

    def __set__(self, obj, val):
        return obj.write(self.address, val)

class Interface(object):
    r = Register(0x00, docstring="the first register") 

我喜欢ipython的用户能够执行以下操作之一:

i = Interface()
i.r? #should show the docstring "the first register"

要么

i = Interface()
i.r(  #should show the docstring "the first register" when parentheses are opened

但是,docstring始终是obj.read返回的int对象中的文件串,而不是指定的docstring.有没有办法在这种情况下显示正确的文档字符串？

如果我不使用描述符但是手动定义它们,则在括号打开时它会起作用:

class Interface(object):
    @property
    def r(self):
        """this docstring will be shown alternatively"""
        return self.read(0x0)

    @r.setter
    def …

我在我的Django项目中使用了像本例中的 Google Style Python Docstrings .当我创建一个类并在docstring中使用属性表示法时,Pycharm总是说 - "未解析的引用".

class Post(models.Model):
    """
    Class for posts.

    Attributes:
        title(str): Post title.
    """
    title = models.CharField(max_length=120)

据我所知,PyCharm没有看到self的title和def __init__()功能,写这个错误,但在Django我从来没有见过使用def __init__()从继承类models.

我该怎么办？这是我的错误还是PyCharm在这种情况下看不到上下文？我应该使用def __init__()或其他什么或以其他方式编写docsting？

现在有人以简单的方式将现有项目中的所有文档字符串从reStructured Text转换为Google格式吗？

看起来拿破仑可以做类似的事情,但看起来很复杂,所以我想我以前是否有人这样做过.任何想法将不胜感激.

我目前正在使用Sphinx和autodoc插件为我的python包编写文档.对于函数返回值,我可以写例如:returns: int: count,告诉sphinx存在类型为int的返回值,命名为count.

我现在有一个函数,它让我的数据库中的项目的前辈:

def get_previous_release(release_id):
    """ Holt Vorgängeritem eines Items mit der ID release_id

        :param release_id: ID des items für das Release
        :type release_id: int

    """

    if not isinstance(release_id, int):
        raise ValueError('get_previous_release expects an Integer value for the parameter release_id')

    try:
        release = my_queries.core.get_by_id(release_id)
    except IndexError:
        raise LookupError('The item with id {} could no be found'.format(release_id))

    if 'Alpha-Release' in release.name:
        release = AlphaRelease(release.key, release.name, release.state)
    elif 'Beta-Release' in release.name:
        release = BetaRelease(release.key, release.name, release.state)
    elif '-Release' in …

在Python中dir()返回当前本地范围中的名称列表. __doc__返回对象的完整文档字符串.

如何列出当前本地范围内的所有名称并打印每个项目文档字符串的第一行？

为了详细说明:对import numpy as np我想获得通过返回的所有名称的简短描述的列表,dir(np)如print(np.nonzero.__doc__.split('.', 1)[0]).

我怎样才能做到这一点 ？

我正在查看某人的代码，其中到处都有这种“文档字符串”：

SLEEP_TIME_ON_FAILURE = 5
"""Time to keep the connection open in case of failure."""

SOCKET_TIMEOUT = 15
"""Socket timeout for inherited socket."""

...

根据 Python 文档，文档字符串仅适用于模块、类或方法开头的上下文。

上述不规范做法意味着什么？为什么 Python 允许这样做？这对性能没有影响吗？

有没有一种方法可以以与方法和函数文档字符串相同的方式自动生成数据类的文档字符串？我通过帮助/搜索没有找到任何有用的东西

from dataclasses import dataclass


@dataclass
class ExtractionConfig:
    """
    
    """
    gcp_bucket: str = None
    gcp_key: str = None
    log_file: str = None
    log_backup_count: int = 3
    delete_remotely: bool = True

当我尝试手动添加它们时，我得到未解析的引用：

Python 3.12有这样type的说法。如何正确记录类型别名？

我试过：

type Number = int | float
"""Represents a scalar number that is either an integer or float"""

但这似乎没有将文档字符串与别名关联起来。我尝试将文档字符串放在=别名定义之后和之前，但这生成了错误。