hi there serdar gagalow pure for infoworld at idg in this episode of smart python we're going
to look at python's docstring functionality this is a way to embed documentation for your python
programs directly in the code now if you're relatively new to python you probably document
your code one of three ways one you put comments in line with the code to explain what's going on
two you have a sidecar file maybe it's in plain text or markdown format
where you describe what's going on in your code or number three you have no documentation at all well
don't feel bad about that last one we all do it but doc strings give you one less excuse to not
bother documenting your code your documentation can be included in line with the code itself
and in a format that's consistent with the way the rest of python looks
that way you don't have to expend as much effort adding documentation as you would to
write it separately now a docstring in python is nothing more than a standalone python string
typically triple quoted to make it easier to turn into a multiline string when such a string appears
as the first line in a certain code block it's automatically transformed by the python runtime
into a docs string here's a simple example of this here we have a function named main and the first
line of the function body is a standalone string whenever that happens that string is transformed
into the docstring for that function it becomes the doc attribute for the function object
if we run this code we can see how that docs string can be accessed programmatically
it can also be accessed by way of third-party tools that generate documentation from code
such as the sphynx tool and i'm going to talk about that more in a future video in the second
example here we have a doc string for the entire module the docs string for the function was the
first line of the function and so the same goes for a module dock string it's the first line of
the module and we can access this dock string by way of the global doc object for the module itself
if we import this module somewhere we can see the docs attribute on the module object another thing
docstrings can do is provide details that python's help function can access now i haven't talked much
about the help function yet so that's likely to be another subject for a future video as well
but the short version is that help lets you get interactive information about python objects
if i import this module main one and use help on the module i will get back that module's dock
string as part of the feedback along with docs strings for all the functions in the module too
and likewise if i run help on main.main i get the functions dot string directly let's take
a look at a slightly more advanced docstring example this one uses classes we also have the
same pattern here the doc string for the class is the first line of the class definition as a string
the doc strings for each class method are just the first lines for each method as a string now when
we run all of this you can see how each of these elements can be obtained programmatically and when
we import this module and run help on it we get a whole wealth of information about everything
in there and of course we can run help directly on each object in the module such as the class object
a simple doc string does not have to follow any particular format as long as it's informative that
said a few formats for doc strings have emerged over time one of them is the format used by again
the sphynx documentation system sphinx parses dock strings to generate information about an object as
well as what parameters it takes the parameter types what's returned and the return type
if this is a function and what exceptions might be raised by the object now a dock string this
detail doesn't need it for a simple program but if you're creating a library for others to reuse
you will want to supply explicit details that can be readily transformed into documentation
in future videos i'll talk more about the automated tooling used to generate documentation
from docstrings such as the aforementioned sphinx and i'll also talk more about the
way the help system works in python especially when you use it in an interactive environment
and how dark strings work more with that that's it for this video if you liked it please leave a
comment below don't forget to subscribe to the idg tech talk channel on youtube and for more
smart python and more dev with zurdar be sure to follow me on facebook youtube and infoworld.com