如何在 Python 中记录字段和属性？

发布于 2024-11-08 23:18:58 字数 413 浏览 4 评论 0 原文

在 Python 中记录类或方法很容易：

class Something:
  """ Description of the class. """

  def do_it(self):
    """ Description of the method. """
    pass

  class_variable = 1 # How to comment?

  @property
  def give_me_some_special_dict(self):
    """ doesn't work! Doc of general dict will be shown. """
    return {}

但是如何记录字段或属性以便在 API 文档或帮助中使用？

原文

It's easy to document a class or method in Python:

class Something:
  """ Description of the class. """

  def do_it(self):
    """ Description of the method. """
    pass

  class_variable = 1 # How to comment?

  @property
  def give_me_some_special_dict(self):
    """ doesn't work! Doc of general dict will be shown. """
    return {}

But how to document a field or property for usage in API docs or help?

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

情释 2024-11-15 23:18:58

Python 有一个 PEP (257)定义文档字符串约定。关于属性的文档，它指出：

立即出现的字符串文字
在顶部进行简单的分配后
模块、类或 __init__ 的级别
方法称为“属性
文档字符串”。

因此以下内容被视为记录属性：（

class Foo(object):
  velocity = 1  
  """Foo's initial velocity - class variable"""

  def __init__(self, args):
    self.location = 0.0 
    """Foo's initial location - instance variable"""

编辑：修复了第二个文档字符串）

Python has a PEP (257) that defines Docstring Conventions. Regarding documentation of attributes, it states:

String literals occurring immediately
after a simple assignment at the top
level of a module, class, or __init__
method are called "attribute
docstrings".

So the following are considered documented attributes:

class Foo(object):
  velocity = 1  
  """Foo's initial velocity - class variable"""

  def __init__(self, args):
    self.location = 0.0 
    """Foo's initial location - instance variable"""

(Edit: Fixed second docstring)

回复收藏 0 原文

白馒头 2024-11-15 23:18:58

使用帮助在 python 解释器中记录属性对我来说效果很好，请参阅 proprerty 文档< /a>. 注意：IPython 的神奇帮助运算符 ? 没有显示属性文档字符串。

>>> class foo(object):
>>>    def __init__(self, bar):
>>>        self._bar = bar
>>>    @property
>>>    def bar(self):
>>>        """bar property"""
>>>        return self._bar
>>> help(foo.bar)
Help on property:

    bar property

在 Sphinx 中，您必须使用 :members:< /code> 指令到文档属性，请参阅 autodoc 文档。对我来说就像一个魅力！

如果使用 :members: ，Sphinx 也会记录属性。属性的文档字符串可以作为属性前面的注释给出，但在散列标记后面使用冒号，EG #: foo attribute。来自 Sphinx autodoc 文档：

对于模块数据成员和类属性，文档可以放入具有特殊格式的注释中（使用 #: 开始注释而不只是 #），也可以放入定义后的文档字符串中。注释需要在定义之前单独占一行，或者在同一行的赋值之后。后一种形式仅限于一行。

Documentation of a property in the python interpreter using help works fine for me, see proprerty documentation. Note: IPython's magic help operator, ?, did not display the property docstring.

>>> class foo(object):
>>>    def __init__(self, bar):
>>>        self._bar = bar
>>>    @property
>>>    def bar(self):
>>>        """bar property"""
>>>        return self._bar
>>> help(foo.bar)
Help on property:

    bar property

In Sphinx you must use the :members: directive to document properties, see autodoc documentation. Works like a charm for me!

Attributes will also be documented by Sphinx if :members: is used. Docstrings for attributes can be given as comments preceding the attribute, but using a colon following the hash mark, EG #: the foo attribute. From the Sphinx autodoc documentation:

For module data members and class attributes, documentation can either be put into a comment with special formatting (using a #: to start the comment instead of just #), or in a docstring after the definition. Comments need to be either on a line of their own before the definition, or immediately after the assignment on the same line. The latter form is restricted to one line only.

回复收藏 0 原文