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.

00:27 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.

00:39 Here we have the Python IDE called Thonny. It’s a very useful IDE. It comes with Python 3.7. It’s very useful, I quite like it, but that’s not what this tutorial is about.

00:51 There is actually a great tutorial, both written and video, on the Real Python website. There’ll be a link to that, if you’re interested, in the text just below the video.

01:00 So, we were going to send str (string) to the help() function.

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.

01:31 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.

01:50 Now, you might be asking how this particular output’s generated. Well, since everything in Python is an object, you can directly examine the directory of the object using the dir() command.

02:01 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 '__doc__'.

02:16 Now, keep in mind that double underscore (__) in Python is referred to as dunder, so moving forward in this tutorial, let’s continue using that convention.

02:26 If we further examine this .__doc__ property by sending it to the print() command—let’s do that right now—

02:37 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.

02:57 The .__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.

03:21 There you go. So, it won’t let you do that. However, say we were to set up our own little function called say_hello(). It doesn’t do a lot.

03:39 It just says, Hello <whatever your name is>, is it me you're looking for?

03:50 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

04:14 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.

04:38 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.

05:03 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.

06:03 All multi-lined docstrings have the following parts: a one-line summary line, a blank line proceeding the summary, any further elaboration for the docstring, and finally, another blank line.

06:17 All docstrings should have the same max character length as comments, which as covered earlier is 72 characters. Here, we can look at an actual docstring formatting example.

06:29 The words are not from a particular method docstring or anything like that—they’re just there to help hammer home the point of the formatting example.

06:40 However, it does follow the given example of including a summary line, just here, followed by a single blank line,

06:51 which is then followed by a little bit of further elaboration around the docstring. And as you can see here, it says Within this section, […] elaborate further on details as appropriate.

07:04 You obviously don’t want to add things that are either redundant or not helpful—you want it to be succinct and useful.

07:12 And then after the triple double quote, to close it, you’ve got another blank line. And here is a comment saying this is where your code should continue.

07:22 So there you have a docstring formatting example.

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.

07:42 We shall explore all of these different types in the next video. See you there!