Add a utility to get docstring node for module/class/function

[Jackenmen]

Something similar to ast.get_docstring() could be useful to find docstrings more easily.

Could be even better, if it were available at Module.docstring, ClassDef.docstring, FunctionDef.docstring but this might not fit your API design that well, especially that docstring isn't a special part of python's grammar and is just a regular string and only special thing about it is that it's a first statement in module/class/function.

My own use case for such utility would be modifying a class's docstring or adding it if it's missing in a visitor. I can obviously do it without such utility, but I think it would make it easier.

[mvismonte]

@jack1142 I can definitely see how this would be useful. As far as I know, we don't have any doc string APIs. The recommended way of doing something like this would be to create a Metadata Provider and reference that in your visitor/transforms in order to determine if a module/class/function has a docstring and making the appropriate action based on that.

I'm sure that's something that would be useful for others, so feel free to put up a PR if you're interested in putting that together =)

[jimmylai]

Yeah, build a DocstringProvider will be very useful.

[Jackenmen]

I'll let someone else make this, I won't have enough time to make this, just wanted to put up this feature request :)

[lensvol]

@jack1142 Will you accept a PR for this or it would be done by someone from your team?

[Jackenmen]

@lensvol I'm not in the team :) But from what I know, maintainers of this project are welcome to PRs from outside.

[lensvol]

@jack1142 Sorry, I was actually trying to mention @mvismonte but my thumb slipped :) I am currently working on something similar, will try to see if it fits the purpose of this issue.

[jimmylai]

@lensvol Yes, your PR will be very welcome! We've accepted PRs from a couple external contributors. https://github.com/Instagram/LibCST/graphs/contributors

[jimmylai]

We recently start adding more helper functions to achieve write less and do more.
We recommend add simple and read-only helpers as attributes of CSTNode, e.g. SimpleString.prefix, quote, raw_value.
https://libcst.readthedocs.io/en/latest/nodes.html#libcst.SimpleString

Docstring is the first string literal statement of module, function or class. It falls under the simple and read-only helper category. So make them as Node.docstring with type Optionoal[str] makes sense.

[jimmylai]

get_docstring helper is implemented in #254
It'll be available in the next LibCST release.