david alfonso

Khal: Codebase review

Project information


High-level analysis

This analysis is based on setup.py contents and on a first look at the code.



Runtime dependencies:

Testing dependencies:

Extra dependencies:

Package organization

Entry points

Two console scripts:

  1. khal = khal.cli:main_khal, which provides a command-result terminal experience.
  2. ikhal = khal.cli:main_ikhal, which provides a TUI (terminal-user interface) handled by code in khal.ui.

Configuration and data files


Calendars (data)


The following diagram tries to represent the components and relations of the khal (cli) application. This is not complete by any means, many pieces are missing and some might be wrong.

Object-oriented design

The khalendar package contains code which is more object-oriented than in other khal's modules. Let's analyze its classes:

The CalendarCollection class can be seen as this package interface. It uses composition to make use of the SQLiteDb class implementation and also is composed of one Vdir object per configured calendar. It also allows CRUD of Events saved in the SQLite cache and in vdirs using multiple criteria.

Events are represented as Event class instances, which is a base class for different derived classes:

The vdir module makes use of many OO design concepts:

Besides the khalendar package, the other interesting package is ui, which contains multiple classes following urwid's object oriented development design.

Python techniques

    with self._backend.at_once():
        event.etag = self._storages[event.calendar].update(event.href, event, event.etag)
        self._backend.update(event.raw, event.href, event.etag, calendar=event.calendar)
        self._backend.set_ctag(self._local_ctag(event.calendar), calendar=event.calendar)

There is much more in khal and I recommend you to take a look at the code and find out by yourself ;-)