有没有一种用`python-attrs`记录属性的好方法？

Question

I'm used to documenting my __init__() function with a docstring, but I would like to take advantage of the benefits of the attrs package. The docstring is useful in IPython or a Jupyter notebook, so I can see what the parameters mean. Is there a good way to do this? In this example code:

@atrr.s
class Coordinates(object):
    """ A set of coordinates
    """
    x = attr.ib()
    y = attr.ib()

"""
In [1]: Coordinates?
Init signature: Coordinates(x, y) -> None
Docstring:     
A set of coordinates
    
Init docstring: Method generated by attrs for class Coordinates.
Type:           type
Subclasses:
"""

how can I describe the x and y variables to the user? For example, how can I specify that these are in degrees?

Answer 1

In Python, the documentation of attributes and (more importantly) __init__ arguments happens in the class docstring , therefore the presence of attrs is not important in this case:

@attr.define
class Coordinates:
    """
    A set of coordinates.

    :param int x: Foo in degrees.
    :param int y: Bar in degrees.
    """
    x: int
    y: int

For more information check out RTD's docs on writing docstrings .

If you don't like this format, another common one is called Napoleon and comes from Google: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html