Docstrings are built-in strings that support project documentation. They are very useful and vary slightly depending on what you are creating them for (scripts, methods, functions, and so on). To learn more, check out Thonny: The Beginner-Friendly Python Editor.
Documenting With Docstrings (Part 1)
00:00 Welcome to Part 4 of the Real Python tutorial for Documenting Your Python Code. Here we will introduce documenting your Python code using docstrings, starting with some background on docstrings and how they work.
00:12 All the documenting that you do in Python is based around docstrings. Now, what are docstrings? Docstrings are built-in strings that when correctly configured can help your users—and perhaps more importantly, yourself—with documenting your project.
Python also has a built-in
help() function in conjunction with docstrings that prints out the object’s docstring to the console. Now, the best way to understand that is to actually look at an example, so let’s do that now.
01:08 Now, as you can see, it comes up with a lot of information—quite a bit more than you’d probably want to go through in an online tutorial. So what we want to look at is this part in particular, just that first little spiel. And here, it tells you exactly what it does: it creates a new string object from the given object.
If encoding or errors is specified,
then the object must expose a data buffer
that will be decoded using the given encoding and error handler. I’m not going to read anymore. So by sending
str to the
help() function, we receive back an explanation around what it does, its general usage, and how it handles errors.
So let’s try that right now on
str. What we get back by sending
str to the directory command is quite a large number of properties. The one that we really want to investigate though, is
you see that we receive the first paragraph of the
help() function result. This means that we have found the location within the object where the docstring is kept. Now that we know where it is kept, we can directly manipulate the property. Now, while there are restrictions for builtins, any other custom object can be manipulated.
.__doc__ attribute for
str can’t be manipulated because, well,
str is a built-in function of Python. So if we did attempt to do anything to the
.__doc__ attribute of
str, we would get a traceback error.
Alrighty, so that’s set up. Now, if we were to attempt to manipulate the
.__doc__ attribute of this particular function, we should be able to do that, because it’s not a builtin. We’ve created this ourselves, and so therefore it shouldn’t be an issue
trying to manipulate it. Oop!
"style" doesn’t have two e’s in it, does it. There we go! So now, if we were to go
help(say_hello), there you go!
A simple function to say
hello, Richie style. I forgot a period, but that’s okay.
And that’s a really simple example of how to create your own
.__doc__, or docstring, if you will. Now finally, Python has one more feature which helps simplify docstring creation. Rather than directly attempting to manipulate the
.__doc__ property, placing the string literal directly below the object will automatically set the
.__doc__ value, as can be seen here.
Note the triple double quotes (
""") at the start and end. So, there you have it! Now that the background of the docstring has been covered, you can move on to understanding our next segment: types of docstrings and what they should contain. The standard PEP 257 contains the conventions followed for docstrings.
05:25 The purpose of a docstring is to provide your users with a brief overview of the object. They should strike a balance between being concise enough to be easy to maintain, yet elaborate enough to allow new users to understand their purpose and how to use the object. In all cases, the docstrings should use the triple double quote string format.
05:45 This should be done whether the docstring is multi-lined or not. As a minimum, a docstring should be a quick summary of whatever it is you’re describing and should be contained within a single line. Multi-lined docstrings are used to further elaborate on the object beyond the summary.
07:27 Docstrings can be further broken up into three major categories: class docstrings for class and class methods; package and module docstrings for package, modules, and functions; and lastly, script docstrings for scripts and functions.
Become a Member to join the conversation.