Programming is just easier with Pydoc

by Christopher Roach


Well, I almost made it yesterday, I promised two more posts for the day in my first blog of the day and I almost delivered. Alas, in the end, sleep won over and I just had to give in. Nevertheless, I did finally finish my third posting and here it is now for your viewing pleasure.




In this entry I will cover one of my favorite features of the Python programming language—its documentation tool pydoc.




pydoc is a tool that comes with Python that can be used for viewing and generating Python documentation. The main reason I love this feature is because it means that everywhere I go, I have easy access to Python's documentation. Thus, I don't need to carry heavy books, or download extra documentation, and best of all, its all accessible from the command line, so I can access documentation while programming without even switching applications. The pydoc documentation tool can even be accessed from within Python's interactive interpreter. What this means is that if I need to use Python for a simple task like parsing files to make repetitive changes to the text, then I can do so by firing up the Python shell and typing out my program and if I can't remember how to do something I just import pydoc and look it up in the documentation.




What I propose to do in this blog is just go over a few of my favorite features of Python's built-in documentation tool. I'll go over how to view and search documentation, how to use pydoc in the Python shell, how to view HTML documentation using a built-in web server, and how to generate HTML documentation for your own python files.




Why don't we start with using pydoc from the command line. Let's say that you're programming in Python and you find you've forgotten how to quit a program. You remember that there is function in the sys module, but you can't remember the name of the function (I know you can probably guess that its sys.exit(), but bear with me, it was late when I came up with this example). What do you do? Well, in this case you're going to call the pydoc program from the command line, like so:





$ pydoc sys




Keep in mind that the dollar sign, '$', is the command prompt and not part of what you'll actually type into the Terminal. Once you've typed in the line above and pressed Return, you should see something that looks somewhat like a man page, and as such, it will act like a man page as well. So, since we are looking for a function, we can narrow down our search by pressing the forward slash, '/' (just like in Vi, this allows you to do a text search), character and typing in the search term, in this case we will type in 'FUNCTIONS' (yes, case does matter, so make sure it's in all caps), then press Return again to start the search. Subsequent searches for the same term can be performed by repeatedly pressing forward slash '/' and Return. You can also use the arrow keys to navigate the documentation or just hit the space bar to scan through a page at a time, and to quit your pydoc session, just type the letter q at any time.




Well that pydoc command works great if your at a command prompt, but what do you do if you're currently in the Python interactive shell and you need to look up something in the documentation? Well, you could always suspend your session with a Ctrl-z, follow the instructions above, and then enter back into the shell where you left off by typing in fg and Return. Another option would be to import the pydoc module directly into your current Python shell session and use the help command to find the documentation you need. Below is an example of how we might check the documentation for the sys module, like we did in the last paragraph, but this time during an interactive Python session.






>>> import pydoc
>>> import sys # Import this in order to check its documentation
>>> pydoc.help(sys)





So, now we've accessed the pydoc tool from the command line and from Python's own interactive shell. The only thing left to do is get our documentation into a nice HTML document.




If you'll remember earlier, I mentioned that you can generate HTML documentation using pydoc. Below is just one example of how you can do this (by the way, the open command just launches whatever application is the default for dealing with the specified file. In my case, it would open the hello.html file in Safari):






$ pydoc -w hello > hello.html; open hello.html





The final feature of the pydoc tool that I want to show you is the web server feature. Basically, by calling pydoc with the -p option and passing to it an open port number, you will start a web server that will allow you to access all of the Python documentation on your system through a web browser, and by "all", I mean both Python's own documentation and documentation for your own files as well (assuming you've used docstrings correctly and you've added your file's location to the PYTHONPATH environment variable). Below is the command that will start your pydoc web server on port 9999:






$ pydoc -p 9999





Once, you've started your pydoc web server, you can see all the documentation by loading the following url in to the web browser of your choosing:





http://localhost:9999/




So, that's it for now. Those are all my little tips and tricks that I use on a regular basis. Once you get used to the having all the documentation you need right there at your fingertips you'll find it hard to go back to other languages that aren't quite as accommodating. You'll also appreciate the ease with which you can document your own code just by adding a few lines to the beginning of each function, method, class, module, etc.




I look forward to talking to all of you again very soon...see you in my next post.



If you know of, or find, any other interesting uses for the pydoc tool that I haven't covered here, make sure you leave a comment for the rest of us so we can get some use out of it as well. I know I'm always interested in learning a few new tricks.


5 Comments

jnoller
2005-10-31 09:41:23
Thanks!
Nice! I had completely forgot about spawning the pydoc server locally for STL access.


Another useful doc thing I found over the weekend is the Edgewall Software Python Sidebar (http://pyjesse.blogspot.com/2005/10/python-sidebar.html) for Mozilla/Firefox Browsers.


jnoller
2005-10-31 09:43:30
Thanks!
I forgot to mention that it might be a cool project to tie links to a local Pydoc server into the sidebar for access to local modules/docs.
christopher_roach
2005-10-31 13:42:16
Thanks!
No, no, no--thank you for reading the blog and giving me such a nice comment. And also, thanks for the link as well. I can't wait to get home and give it try, it looks really cool.
aristotle
2005-11-01 00:53:45
Re:
I don’t know if there’s any obligation for you to post from O’Reilly’s side, since I don’t know what contract is involved with having a weblog here. But the readers come in either from feed aggregators or from weblogs.oreillynet.com, according to the last surveys. In other words, noone will notice if you go missing for a while.


That doesn’t mean noone cares at all. There are a few webloggers here at O’Reilly whose entries I’ve noticed I tend to enjoy (and others whose entries I tend not to). The point is that in each of the cases where I’ve noticed a particular weblogger, it’s because of what they write about and/or how well.


So far, to me you are “the guy who always writes about how he didn’t make his posting schedule.” Please stop that. It really detracts from your otherwise interesting articles.

christopher_roach
2005-11-02 16:02:45
Re:
Well, let me start out by saying thanks for reading the post in the first place--it means quite a bit to me. And, from the tone of the final paragraph, I'll assume that for the most part you approve of my posts, but you could do with out the small talk at the intro. So, let me also thank you for pointing out that the articles are interesting, this really means alot to me.


Now, as for the obligations and so forth--O'Reilly does not hold us to any posting schedule, this is strictly one that I setup myself and that I was hoping to use to develop a bit of a relationship with, what I hope will become, regular readers of my posts. I was really hoping that my comments at the beginning of my articles would add a more human touch to what is otherwise a small tutorial. I can definitely appreciate your point though, and in the future I'll try to limit these comments and instead focus more on the core content of the piece.


That said, I do appreciate your comments and I sincerely hope you continue to visit my blog and offer up any more compliments, recommendations, requests that you see fit. Its always nice to have someone point out ways that you can make your writing a bit better. Thanks again, I hope to see you here again soon.