How to write a new importer

Gourmet's importers live in...

src/lib/importers/

The base class for all importers is called, "importer" and it is stored in the file called importer.py
Every importer subclasses (or at least uses) the importer base class.

I always find it useful when playing with python programs to just see how things work at the python shell. Here's an example of some python code typed at the shell to make use of the importer interface:

>>> import gourmet.recipeManager
>>> import gourmet.importers.importer
Loading  gnomeprint  failed: trying  win
Loading  win  failed: trying  lpr
>>> rd = gourmet.recipeManager.default_rec_manager()
>>> importer = gourmet.importers.importer.importer(rd)
>>> importer.start_rec()
>>> importer.rec['title']='My new recipe'
>>> importer.rec['instructions']='These are my instructions.'
>>> importer.start_ing()
>>> importer.add_amt(2)
>>> importer.add_unit('cups')
>>> importer.add_item('cheese')
>>> importer.add_key('cheese')
>>> importer.commit_ing()
>>> importer.commit_rec()

As you can see, the recipe importing is quite simple -- start_rec() starts a new recipe and commit_rec() finishes it. In the between time, you can add Recipe attributes to the .rec attribute, which is a dictionary.

The model for the importer is a model useful for nearly all recipe formats you might import -- formats where you will get one recipe at a time (i.e. recipes then ingredients). If you have a database to import where the ingredients are separated out into a different table, you will have to do things a little bit differently.

When you instantiate the base importer class, there are some keyword arguments you can use for convenience.
Here's a copy of the documentation for the base importer's init method:

        rating_converter should be True if we will get ratings in a
        format other than an integer from 1-10. If it is True, the user will
        be asked to convert from whatever numbers of text ratings are in to
        gourmet's star system (1-5 stars, with half-stars, represented
        internally as integer 1-10).

        If you are creating a subclass, the other arguments should be
        accepted by your subclass and passed onto us as are.

        total is used to keep track of progress with function
        progress. If we are doing multiple imports, we will get a different
        number here.

        prog is our current progress-bar/progress-tracking method.

        rd is our recipe database instance.
        """

For most plain text imports, you'll want to use the setting do_markup=True and convert_ratings to True.

To write a script to do a one-time import, this page covers all you need to know. In order to write an importer to include in Gourmet, you'll need a bit more. I recommend looking at some of the other importers in the importers/ directory. Look at one that is similar to what you're creating (i.e. look at one of the xml format importers if you're importing xml).

To "register" your importer with gourmet so it will show up in the user interface, you need to include it in the file:

src/lib/importers/__init__.py

The format there is a bit complicated, but if you just copy the setup of the other importers, you should be all set.