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()!