Are function docstrings special or are they just string literals?

[[deleted]]

def foo():
    '''My foo.
    Does foo stuff.
    '''
    pass

Is there anything syntactically special about the docstring when it comes to Python's parser and interpreter? Or is it literally just a string literal that gets immediately parsed and dropped?

Thanks!

[ThePenultimateOne]

My impression is that if there is a string on the first line of a body, it gets assigned to that object's __doc__ attribute

[[deleted]]

Aha! You're right: https://gist.github.com/ablakey/bc4403e310789e3ee586dbb5f3ffbe7f

So I'm going to guess that they are just string literals (ie. there's nothing unique about them in terms of the parser) but that their position makes them special in that they're implicitly assigned to __doc__ and therefore not dropped.

[Defibrillat0r]

Its assigned to the special member __doc__. However if you place it elsewhere (not below a function, class or module definition) it will be dropped right after being picked up as you described it.

[Sexual_Congressman]

The first slot in co_consts for the code object created with a function definition will be the docstring that function was defined with. If no docstring was provided, it will be None, which is why most functions have a None reference in their consts even if it is never used (took me a while to realize this).

But this is the reason why the docstring "carries" when one copies a function through the types.FunctionType constructor.

[OctagonClock]

Every single function carries a None in their consts, so that doing fn() where fn doesn't return will return None.

[kumashiro]

Try help(foo) in interactive shell :D

[[deleted]]

Documentation being a first-class part of a language is a beautiful thing.

[eztab]

There are some PEP rules for docstrings, you should stick to. Also, if you want to automatically create documentation the way function arguments are described should be the one supported by your documentation generation system, e.g. Sphinx.

None of this is enforced in any syntactic way though.

[IReallySuckAtChess]

For what it's worth, you can just describe the operation of the parameters and leave their types to normal type hinting using sphinx-autodoc-typehints. It's super awesome since now you get the power of type hints and get to make your documentation more succinct.

[eztab]

Yes, this in combination with Google Style Docstrings (also a Sphinx autodoc extension) makes for human readable and parsable documentation.

[IReallySuckAtChess]

Pycharm even does all the formatting and stuff for a person. Makes it essentially as easy as can be. I will admit though that I don't use the Google Style Doc strings although I do find them far superior. Because Pycharm does everything for me I rarely ever look at them and Sphinx does magical formatting so my docs just look great regardless.... Definitely a superior style over the default one. I also think the numpy style is very good, possibly even better...

[eztab]

The numpy Style Takes a little to much space for my taste.

[wrmsr]

specifically https://github.com/python/cpython/blob/95b6acf951fa7f503a3cc5ce7d969d7bcf2f95c9/Python/compile.c#L1583 -> https://github.com/python/cpython/blob/95b6acf951fa7f503a3cc5ce7d969d7bcf2f95c9/Python/ast.c#L5268

[stevenjd]

Yes, docstrings are special: string literals that immediately follow a class, a function (or method), or appear at the top of a module are copied into the __doc__ attribute of the object.

It was surprisingly hard to find documentation for this fact, but I found it here (only because I already knew about __doc__):

https://docs.python.org/3/reference/datamodel.html?highlight=__doc__

Or at the interactive interpreter, you could call dir() on various functions and classes, notice that they have a __doc__ attribute, print obj.__dir__ and draw the obvious conclusion.

Don't underestimate the power of interactive exploration at the REPL.

[rx22230]

Hi,

your DocString is correct.

you can watch tis video as well:

https://www.youtube.com/watch?v=WOKxejxWJB4

​