Exploring Ways to Access Docstrings

00:00 One of the most important things about docstrings is that they’re actually code objects, and they can be accessed at runtime. A few of the ways you can access them include the .__doc__ attribute found on modules, classes, and functions, the built-in help() and the pydoc module in the Python standard library.

00:17 So let’s try it out. Starting the terminal, I’ve got the two docstring examples from the previous lessons saved as Python files, and one more file, magical_characters.py, that we’ll look at in a minute.

00:29 You can grab all of these files from the downloadable course resources. View the files with ls

00:36 and you can quickly examine the contents of the files we saw in the previous lesson using the cat command: cat one_line_docstring.py shows us the determine_magic_level() function,

00:50 and cat multiline_docstring.py shows us the get_harry_potter_book() function, same as before, with the same docstrings. We’ll clear this and open up the REPL. First, import both functions from one_line_docstring: import determine_magic_level from multiline_doc string: import get_harry_potter_book

01:17 and for comparison, also import a module from the standard library. How about math: import math? So for the most direct way to view a docstring, try printing the .__doc__ attribute.

01:29 print(determine_magic_level .__doc__) returns, Multiply wizard's age by three to reveal their magic level. While printing get_harry_potter_book() .__doc__: print( its multiline docstring with the summary, parameters, and return value.

01:49 And because .__doc__ returns the docstring as you wrote it, you do see leading and trailing blank lines for the multiline docstring. Then try printing math.__doc__.

02:00 This module provides access to the mathematical functions defined by the C standard. Seems a bit short for a module, but you’ll find the behavior with .__doc__ is a little bit different when it comes to Python built-ins.

02:11 And of course, accessing docstrings via .__doc__ is quite bare-bones, so it’s best you use it for programmatic access to docstrings. In an interactive session like the REPL, the built-in help() function is a better choice.

02:24 Try it on the math module: help(math). And as you can see, you get a lot more detail. This is what’s great about the help() function, especially when used with built-ins like math.

02:37 You can page forwards and backwards with f and b,

02:41 and even search for a text string using /, like /gcd takes you to the entry on the gcd() function, which just says greatest common divisor.

02:53 That’s accurate. Exit this dialogue with q, and while you can also also use help() with your user-defined functions, like help(get_harry_potter_book),

03:05 it’s not quite as impressive as with math. It’s pretty much the same as accessing .__doc__ directly. Exit with q, and exit the REPL with Ctrl+D.

03:17 Clear. Okay, I mentioned one more tool, and that’s pydoc. Now it’s time to look at this magical_characters.py file. cat magical_characters.py,

03:28 a module docstring saying a module for adding and listing magical characters. Then you have a function add_characters() with a docstring: """Add a new magical character""", and an if __name__ == "__main__": guard before printing the result of running the add_characters() function.

03:45 Now look at what happens when you apply the built-in pydoc module to this file. python -m pydoc magical_characters

03:54 and hey, you’re back on the help screen. Under the name, you have the filename, as well as the docstring. Then a list of functions with their corresponding docstrings, and where the file is located on your system.

04:06 This is basically a direct way to access information about a Python module without opening up a REPL session first. Exit with q again, and you’ll find pydoc has even more features than we can cover in this lesson.

04:19 But one more really cool one is that it can generate an HTML page out of your docstrings: python -m pydoc -w magical_characters.

04:32 The -w flag is what tells pydoc to write an HTML page. The result is wrote magical_characters.html, and with ls you can see magical_characters .html now exists, and you can open this in your browser.

04:47 Since I’m on macOS, I’ll use open with the -a flag to open this file with Google Chrome: open -a Google Chrome magical_characters.html

05:00 And hey, it’s a webpage. A very, very basic one, but still a webpage. Cool, right? Now that you’ve seen how to access docstrings, next lesson we’ll get to the fun part: writing them.

05:12 See you there.