exuberant-ctags + emacs!

Here is rule number one for any python development with Zope3: use ctags.

ctags is a program that goes through an entire source tree and creates a database of where all functions and class definitions are located. This way programs that support ctags can do really fast lookups and give you the location of some function or class definition. You will no longer have to sheepishly ask on irc where such and such Interface or Class is located – and frankly no one else knows and everyone just uses ctags. Here are the steps involved in setting up and using ctags with emacs on ubuntu.

1. Install ctags

   
       $ sudo apt-get install exuberant-ctags
       

2. Go to the root of your source tree and type at the command line:

   
       $ ctags -Re
       

   this will create a file called TAGS in the local directory

3. Use emacs. To do a tag lookup type in any emacs buffer M-. (that is Alt-. for those of you who don’t know emacs command syntax)
4. Type in the name of the tag you are looking for. If you don’t know the whole name, emacs supports tab completion in this area. After typing the word hit Enter/Return
• The first time you do this, it will ask you to specify the location of the TAGS file, so just enter it in (it is in the root of your source directory) and hit enter.
5. You should now be looking at the definition of the class/interface you were looking for and the file you are in specifies the path.
6. Catch-22s:
   • Occasionally, due to polymorphism, functions and classes in different packages can have the same name and the tags will go to the first one it finds. So searching for __init__ doesn’t really do any good
   • Sometimes the location where something is defined is not where you should be importing from. For example, if there is a class SomeClass defined in package/subpackage.py, and package/__init__.py imports SomeClass from subpackage, then you are really meant to import SomeClass like

     from package import SomeClass

     and not like

     from package.somepackage import SomeClass

     Certainly the former is shorter and simpler.

7. Other Tips:
   • If you are working in multiple source trees on multiple projects and you want to switch which TAGS database is being loaded, then you can type M-x tags-reset-tags-tables
   • If you want to search for every place where a tag is used in your source (like every time someFunction() is called) you can type M-x tags-search and enter in the search string. To get to the next result, type M-,.
   • Also be sure to check out M-x tags-apropos and tags-query-replace.

For *ahem* vim users *ahem*, there is a vim plugin for ctags found here: http://www.vim.org/scripts/script.php?script_id=273