print(__doc__) in Python 3 script

Question

I can't figure out what does the print(__doc__) do at the beginning of a script, like in this Scikit example.

I have been looking for Python docstrings in google, and it seems __doc__ is useful to provide some documentation in, say, functions. But I can't see what does __doc__ do in the middle of a script.

Answer 1

it seems __doc__ is useful to provide some documentation in, say, functions

This is true. In addition to functions, documentation can also be provided in modules. So, if you have a file named mymodule.py like this:

"""This is the module docstring."""

def f(x):
    """This is the function docstring."""
    return 2 * x

You can access its docstrings like this:

>>> import mymodule
>>> mymodule.__doc__
'This is the module docstring.'
>>> mymodule.f.__doc__
'This is the function docstring.'

Now, back to your question: what does print(__doc__) do? Simply put: it prints the module docstring. If no docstring has been specified, __doc__ defaults to None.

Answer 2

Any function, class or module starting with a string literal has a non-empty __doc__; that initial string is taken as the documentation string; it'll be set to None if no such string is present. See the docstring term definition in the Python glossary.

When you download that Scikit script example, you'll see it starts with such a string:

"""
================================
Recognizing hand-written digits
================================

An example showing how the scikit-learn can be used to recognize images of
hand-written digits.

This example is commented in the
:ref:`tutorial section of the user manual <introduction>`.

"""

The print(__doc__) command simply re-uses that documentation string to write it to your terminal each time you run the script, and any other python tool (like the interactive interpreter help() function, for example) can introspect that same value.