Ability to add a doc string to attr.ib about attrs HOT 12 CLOSED

This is semi-possible now because of the auto_attribs option. With it you can just put the docstring beneath the attribute declaration:

@attr.s(auto_attribs=True)
class SomeClass:
    a_number: int = 42
    """Something descriptive about ``a_number``."""

It's still ignored by Python so help(SomeClass.a_number) doesn't work (in this case it'll just run help(42)) but Sphinx picks it up happily enough which was my main motivation for landing on this page.

from attrs.

I've actually just started documenting the attributes as :param: in the class docstring, which sphinx renders pretty nicely: http://effect.readthedocs.org/en/latest/apidocs.html#effect.Effect

This seems like probably the best solution, since if attrs were to modify the docstring, it'd have to assume a documentation format, which may be wrong (e.g. older projects still use epytext).

from attrs.

There is none; the community way is to put all your docs into the class docstring by hand. Adding templating magic would list likely break along the various consumers of it. 😐

To be fair, there's no boilerplate of repetition. It's just about the position where you put your docs.

from attrs.

I’ve played with it a bit but I’m not sure it’s possible when not using properties that are pretty special. :-/ Gotta dig deeper…

from attrs.

Reading the answers of http://stackoverflow.com/questions/5793306/python-get-doc-documentation-for-instance-variable#5793396 it seems to me that the only reason it work with your properties is they’re methods underneath.

So unless you find a way to add doc strings to data attributes without wrapping them using properties, I’m afraid this is impossible.

from attrs.

Have you considered appending documentation for attributes to the class's docstring? Or the __init__ docstring?

One other thing I noticed is that if you set default to an attr.Factory, sphinx shows the default as NOTHING which is slightly misleading (the reader would have to look down to the class attribute showing the Attribute instance, which will be unfamiliar to most people).

from attrs.

does that work? care to provide a PR/PoC? 😇

from attrs.

Yes, that’s why my init has no docstring. I removed it on Lynn’s request for this very reason. :)

from attrs.

Reading the answers of http://stackoverflow.com/questions/5793306/python-get-doc-documentation-for-instance-variable#5793396 it seems to me that the only reason it work with your properties is they’re methods underneath.

So unless you find a way to add doc strings to data attributes without wrapping them using properties, I’m afraid this is impossible.

You can add docstrings using descriptors.

I suppose that's not different enough from properties though?

class Descriptor:

   def __init__(self, doc_str):
       self.__doc__ = doc_str

   def __set_name__(self, owner, attr):
       self.attr = attr

   def __get__(self, instance, inst_type):
       return getattr(instance, f"_{self.attr}")

   def __set__(self, instance, value):
        setattr(instance, f"_{self.attr}", value)

class Foo:
   bar = Descriptor("Example Docstring")

foo = Foo()

help(foo)

You'll have to excuse me as I just discovered your library after trying out dataclasses for the first time. I was adding my own validators and docstrings to dataclass fields using descriptors. Then someone told me about attrs :)

Edit: I suppose what I did is not exactly what OP is doing.

from attrs.

Somehow param does this. See the "doc" keyword: https://param.holoviz.org/user_guide/Parameters.html#parameter-metadata

from attrs.

Somehow param does this. See the "doc" keyword: https://param.holoviz.org/user_guide/Parameters.html#parameter-metadata

If I read the docs correctly, it just appends a doc attribute to the params. It doesn't sound like it would work with help etc.

And since it came up the other day on StackOverflow to reinforce: the canonical way of documenting attributes of a class in Python is currently in the __init__ docstring. Until a new standard emerges, attrs is following 100% the community ways.

from attrs.

@hynek - what's the best way to specify the doc/help for a particular attribute when using @define and new-style type annotation/etc interface that ends up being in the __init__ docstring in the way you describe?

My specific use case is trying to get this somewhere better:

    time_limit: int = None  # in minutes

from attrs.