The doctrings for fields are usually inside the class object docstring
(formatting of which depending on the docstring style). As CHB said, there
isn't a way to add them to objects.
Maybe there's a way to make this happen, though? Like:
@dataclass
@build_docstring(format="sphinx")
class LameClass:
"I'm a really awesome class, just ask me"
x: int, "Xes are xes"
foo: Optional[str], "Ys are ys"
Then (sphinx-formatted docstring):
>>> print( LameClass.__doc__ )
I'm a really awesome class, just ask me.
:param x: Xes are xes
:type x: class:`int`
:param y: Ys are ys
:type y: str, optional
- Rick
---
Ricky.
"I've never met a Kentucky man who wasn't either thinking about going home
or actually going home." - Happy Chandler
On Wed, Jan 22, 2020 at 4:03 PM Christopher Barker <python...@gmail.com>
wrote:
> On Tue, Jan 21, 2020 at 12:55 PM <cont...@ehsankia.com> wrote:
>
>> Currently, there is no way to add docstrings to fields in dataclasses.
>> PEP257 talks about attribute docstrings (a string literal following an
>> assignment), but these are visual only and not accessible at runtime. My
>> suggestion would be a simple `doc` or `docstring` parameter to
>> dataclasses.field(). Currently the best way to get anything close to this
>> is using metadata, which is much clunkier:
>> `dataclasses.field(metadata={'docstring': 'my description'})`
>>
>
> My first thought is "sure, why not", but then I thought a bit more, and
> I"m not so sure.
>
> docstrings are VERY useful for class methods. but dataclass fields are not
> methods, they are attributes, and usually simple attributes. Which I do'nt
> hink there is any way to attach docstrings to in regular old classes. You
> can crate a property that looks like an attribute, an give it a docstring,
> but if you're going that far, maybe dataclasses aren't the right tool for
> the job.
>
> In fact, I'm not sure it's even possible: if a filed is a simple type, say
> and in integer, how would you give it a a docstring??
>
> In [17]: i.__doc__ = "an integer's docstring"
>
> ---------------------------------------------------------------------------
> AttributeError Traceback (most recent call last)
> <ipython-input-17-94dacc7686e2> in <module>
> ----> 1 i.__doc__ = "an integer's docstring"
>
> AttributeError: 'int' object attribute '__doc__' is read-only
>
> -CHB
>
> --
> Christopher Barker, PhD
>
> Python Language Consulting
> - Teaching
> - Scientific Software Development
> - Desktop GUI and Web Development
> - wxPython, numpy, scipy, Cython
> _______________________________________________
> Python-ideas mailing list -- python-ideas@python.org
> To unsubscribe send an email to python-ideas-le...@python.org
> https://mail.python.org/mailman3/lists/python-ideas.python.org/
> Message archived at
> https://mail.python.org/archives/list/python-ideas@python.org/message/4QMZOHGTUBQLHNHV6Q7UP47DVNHDCPKX/
> Code of Conduct: http://python.org/psf/codeofconduct/
>
_______________________________________________
Python-ideas mailing list -- python-ideas@python.org
To unsubscribe send an email to python-ideas-le...@python.org
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at
https://mail.python.org/archives/list/python-ideas@python.org/message/IG2JEUR3HCFCZO4JBHKE4KI6UPIYS6SF/
Code of Conduct: http://python.org/psf/codeofconduct/
