Understanding Python Docstrings

00:00 Understand Python Docstrings. Docstrings are your biggest help for documenting your Python code. They’re built-in strings that you can configure to hold usage instructions and information about your functions, classes, and modules.

00:17 A Python docstring consists of text in between a pair of three double quotation marks ("""). Most commonly, you’ll read and write function, class, and method docstrings.

00:31 In these cases, the docstring is located right below the line that defines the class, method, or function.

00:48 This code shows an example docstring for a function called greet(). The docstring starts with a single-line description of the function’s purpose, followed by more in-depth information.

01:00 As seen in the excerpt from the Docstring Conventions PEP, which is linked to on-screen,

01:09 docstrings can help to make the code that you’re working with easier to understand. They provide information about code objects, and if you write them well, they will clarify the context and use of an object.

01:22 You can access the information saved in a docstring using the built-in help() function.

01:30 If you call help() on any code object, then Python will print the object’s docstring to your terminal. In the BPython REPL, this is presented on a separate screen, which you can exit by pressing Q.

01:42 An object’s docstring is saved in .__doc__, and you can also inspect it there directly.

01:50 This attribute contains your docstring, and you could read any docstring with .__doc__. However, you’ll usually access it through the more convenient help() function. Displaying a docstring with help() also improves the formatting.

02:05 Other types of docstrings, such as module and package docstrings, use the same triple double-quote syntax. You place a module docstring, right at the beginning of a file, and you write a package docstring at the beginning of a __init__.py file.

02:21 These docstrings provide high-level information about the module or package, as directed by PEP 257.

02:30 The basic syntax for all Python docstrings is the same, although you’ll find them in different locations based on what the docstring is documenting. In this course, you’ll create function, module, and package docstrings.

02:43 If your personal Python project contains classes, then you should document these as well using class docstrings. Docstrings were formalized in PEP 257, but their structure isn’t strictly defined. Subsequently, different projects have developed different standards for Python docstrings.

03:04 MkDocs supports three common types of Python docstring formats: Google-Style docstrings, the NumPy Docstring Standard, and the Sphinx Docstring Format. The Python handler for MkDocs uses Google-style docstrings by default, an example of which is seen on-screen.

03:23 The docstring should start with a one-line summary and then have sections for a longer description if needed, followed by arguments, return values, and relevant exceptions that the function may raise.

03:36 You’ll stick with Google-style docstrings for this course, and in the next section, you’ll add docstrings to your functions.