Hacking guide

Code organisation

The code is splited in two pieces:

• backend : Everything related to document management. May depend on various things but not Gtk
• frontend : The GUI. Entirely dependant on Gtk

Indexation & Search

The code relative to the indexation and the search is mostly in src/paperwork/backend/docsearch.py. Python-Whoosh is used for that and do most of the work.

When starting, Paperwork examine the work directory, and look for new/modified/deleted documents. It then update automatically its index.

The index is stored in ~/.local/share/paperwork/index.

Thread safety

Thread safety is a major issue in Paperwork. We need threads to keep the GUI smooth, but unfortunately, a lot of Paperwork dependencies are not thread-safe. For instance, libpoppler is not thread-safe at all.

A job scheduling mechanism has been implemented (see src/paperwork/frontend/jobs.py). The idea here is to run most of the jobs in the same thread (whenever possible).

Each Job represents ... well, a job to do. Some jobs can be stopped and resumed later (for instance JobDocThumbnailer).

JobFactories instanciate Jobs. They are also used to keep the job recognizable.

Jobs are passed to JobSchedulers. There is one execution thread by JobScheduler. They accept jobs using the method schedule(). The job with the higher priority is run first. If the job added to the scheduler has an higher priority than the active one, the scheduler will try to stop the active one and run it back later.

Jobs can be cancelled (assuming they are stoppable or not active yet). A single job can be cancelled, or all the jobs from a given factory.

There is one main scheduler (called 'main'), and some others used mostly for progress bar updates based on time. The main scheduler is the one used to access all the documents contents and the index.

Note that there are other threads running: The thread of PyInsane and the Gtk main loop.