Python Help and Your Modules

Warren: In the book, we talked a bit about Python's help system. This is something that can give you help on using Python's built-in modules and functions as well as external modules and functions. But we didn't tell you how to add help to your own modules. In this post, we will. I'm going to let Carter take it from here.

Carter: Hi! It's Carter here. This blog post is a guide to adding help to your Python modules. We will be starting with our TempConv module from Chapter 15:

# this is the file "my_module.py"
# we're going to use it in another program
def c_to_f(celsius):
fahrenheit = celsius * 9.0 / 5 + 32
return fahrenheit

First, let's see what help() brings up in Python:

>>> import my_module
Traceback (most recent call last):
File "", line 1, in 
ImportError: No module named my_module

Oops! We forgot that Python can't find our module unless it's in a folder where python can find it. Navigate to this folder in Windows Explorer (or your favourite file browser):

C:\Python25\Lib\site-packages\

Among other things, you should see a Pygame folder, a PythonCard folder, and easygui.py (you might have to scroll down). Save my_module.py there, restart IDLE (or SPE, or Python Shell), and then try importing it again to make sure Python can find it.

Now, let's see what help() brings:

>>> import my_module
>>> help(my_module)
Help on module my_module:

NAME
my_module

FILE
c:\python25\lib\site-packages\my_module.py

DESCRIPTION
# this is the file "my_module.py"
# we're going to use it in another program

FUNCTIONS
c_to_f(celsius)
# this is the file "my_module.py"
# we're going to use it in another program

Not very user-friendly. Let's try changing the comments.

# My Module
# Our first module.
def c_to_f(celsius):
    #converts celsius to fahrenheit
    fahrenheit = celsius * 9.0 / 5 + 32
    return fahrenheit

And now restart IDLE again (this is getting annoying...) and call help():

>>>import my_module
>>>help(my_module)
Help on module my_module:

NAME
my_module
FILE
c:\python25\lib\site-packages\my_module.py
DESCRIPTION
#My Module
#Our first module.
FUNCTIONS
c_to_f(celsius)

Huh. Why didn't c_to_f's comment appear? The answer is that help() uses strings, but supports comments at the start of the program. Let's change my_module again:

"""My Module
Our first module."""

def c_to_f(celsius):
"converts celsius to fahrenheit"
fahrenheit = celsius * 9.0 / 5 + 32
return fahrenheit

And now restart IDLE and use help again:

>>> import my_module
>>> help(my_module)
Help on module my_module:

NAME
my_module
FILE
c:\python25\lib\site-packages\my_module.py

DESCRIPTION
My Module
Our first module.

FUNCTIONS
c_to_f(celsius)
    converts celsius to fahrenheit

There, now that looks a lot better. Also, Python classes display similar help. Try typing this into my_module:

"""My Module
Our first module."""

def c_to_f(celsius):
"converts celsius to fahrenheit"
fahrenheit = celsius * 9.0 / 5 + 32
return fahrenheit

class SampleObject:
"Sample object"
def __init__(self, number):
    "Initializes object"
    self.number = number
def addOne(self):
    "Adds one to the number"
    self.number += 1

And the help() is:

>>> import my_module
>>> help(my_module)
Help on module my_module:

NAME
my_module

FILE
c:\python25\lib\site-packages\my_module.py

DESCRIPTION
My Module
Our first module.

CLASSES
SampleObject

class SampleObject
    Sample object

    Methods defined here:

       __init__(self, number)
           Initializes object
 
       addOne(self)
           Adds one to the number

FUNCTIONS
c_to_f(celsius)
    converts celsius to fahrenheit

One more thing: For help() to work correctly, your string also has to be on the first line of your program (or function, or class, or method), and be indented correctly.
And that's how you can make your modules look great in help()!