Dec 18 2008

Announcing django-swingtime

Posted in Django, Python, Technical § 4 Comments

Update: Added locale / i18n support to the application 2008-12-19

Swingtime is a Django application similar to a stripped down version of iCal for Mac OS X or Google Calendar. Swingtime provides an Event model that acts as a metadata container for one or more Occurrence objects, which in turn describe start and end times for a specific occurrence of an event.

For the impatient:

Swingtime relies heavily upon both the datetime standard library package and the dateutil package, featuring direct support for the dateutil.rrule interface to create occurrences.

A fairly simple example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
>>> from datetime import *
>>> from swingtime import models as swingtime
>>> et = swingtime.EventType.objects.create(abbr='work', label='Work Related Events')
>>> evt = swingtime.Event.objects.create(
...     title='New TPS Cover Sheet',
...     description='Kiss off, Lumbergh!',
...     event_type=et
... )
>>> evt.add_occurrences(datetime(2008,12,1,16), datetime(2008,12,1,16,15), count=5)
>>> for o in evt.occurrence_set.all():
...     print o
... 
New TPS Cover Sheet: 2008-12-01T16:00:00
New TPS Cover Sheet: 2008-12-02T16:00:00
New TPS Cover Sheet: 2008-12-03T16:00:00
New TPS Cover Sheet: 2008-12-04T16:00:00
New TPS Cover Sheet: 2008-12-05T16:00:00

A bit more elaborate example, using the the convenience function create_event:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
>>> # pay day is the last Friday of the month at 5pm
>>> evt = swingtime.create_event(
...     'Pay day',
...     ('pay', 'Payroll'), # alternate means to add EventType on the fly
...     freq=rrule.MONTHLY,
...     byweekday=rrule.FR(-1),
...     until=datetime(2009,4,1),
...     start_time=datetime(2008,12,25,17)
... )
>>> for o in evt.occurrence_set.all():
...     print o
... 
Pay day: 2008-12-26T17:00:00
Pay day: 2009-01-30T17:00:00
Pay day: 2009-02-27T17:00:00
Pay day: 2009-03-27T17:00:00

Features

  • Support for adding complex event occurrences via dateutil
  • Ready-made `MultipleOccurrenceForm for handling complex form input
  • Daily, monthly, and annual view functions
  • Grid-based daily view generator, complete with alternating or sequential EventType based CSS class names
  • Slightly better than average documentation, a few test cases, and commented code
  • Active support (I have to eat my own dogfood)
  • Built-in demo project / application

Requirements

  • Django 1.0+
  • Python 2.5+ (yeah, sorry, Swingtime won't work with 2.3 or 2.4, but I use 2.5+ exclusively; however, should anyone like to contribute the necessary backward compatible patches that don't hamstring any of 2.5+ features, I more than willing to include them).
  • The dateutil package.

Get Swingtime

Settings

Swingtime has it's settings module (conf/swingtime_settings.py) that simulates how each Django project's setting.py file functions. You can overwrite any or all of the configuration parameters described in :mod:swingtime_settings by creating a file in your own project and referencing that file in your project settings using the name SWINGTIME_SETTINGS_MODULE.

For example, from the demo's settings.py configuration:

1
SWINGTIME_SETTINGS_MODULE = 'demo.swingtime_settings'

Demo

Swingtime comes with its own demo project and application. The demo is themed as a Karate studio's website and allows you see and interact with the Swingtime application.

A live demo can be found at http://swingtime.gorgeofeternalperil.com or run locally using the built-in Django development server.

Templates

Currently, Swingtime does not include any templates of its own. The demo project provides some sample templates to use as a guide or starting point.

Perhaps the best thing the sample demo templates do is showcase the ability to add complex event recurrences via the MultipleOccurrenceForm. Browse to a daily view and select a time slot from the left hand column to add a new event starting at the selected time.

Sample data

Within the Swingtime demo is an app named karate, which defines the custom management command loaddemo. This command will pre-populate your initial database with some events and occurrences based upon the current date and time.

Running the demo

If you've checked out from directly from the trunk directory or exploded the latest version tarball, you run the demo from anywhere by changing to the demo directory and running:

1
2
$ python manage.py loaddemo
$ python manage.py runserver

Todo List

  • Add i18n / translation support for demo and demo templates
  • Include a setup installer (I'm not doing easy_install!)
  • Add weekly view
  • Import and export .ics files
  • Add Note support to demo
  • Add more tests
  • Port over to github

4 Comments

Rock Howard on Fri, 19 Dec 2008 08:15:02 -0500 #:

I have been working hard over the last few weeks to improve the django-schedule app (which is almost identical to this app) by adding a bunch of useful views, templates, templatetags, convenience functions and such. Last Tuesday I happened to stumble across the Labix dateutil library and immediately wondered if django-schedule would have been better off by incorporating that library. (The event/occurrence logic was already baked into django-schedule when I got involved with it.)

Last night I just did a major release for django-schedule and so your release could not have been better timed as far as I am concerned. I will be diving into your code shortly with hopes that dateutil and your use of it prove themselves to be worthwhile.

chris on Fri, 19 Dec 2008 12:49:54 -0500 #:

Thank you. This looks extremely useful. Will checkout the code

Rock Howard on Sat, 20 Dec 2008 07:16:02 -0500 #:

It turns out that django-schedule does use dateutil, however they have only exposed a tiny bit of it thus far. I like what you have done with it better. I also like your general model design a bit better except for a few things that are missing such as a Calendar model.

It turns out that both django-swingtime and django-schedule have important capabilities that the other lacks and one way or another I need a django scheduler that does it all! My plan for making that happen is not fully formulated yet as I am still examining the two code bases.

Mathijs de Bruin on Mon, 22 Dec 2008 11:58:00 -0500 #:

Wonderous, how three people can work on solving practically the same problem. About a month ago I have written a similar application.

Allthough it does not incorporate recurring events it DOES support .ics exports using the vcard library. Also, I have written a template tag which wraps the built-in Python calendar display and have written views and demo-templates that make use of it. With it you can chronologically browse throuh events.

You might want to borrow some of that functionality so please, steal my code. (And I might grab some of yours, or maybe your entire app and hack in the .ics export myself.)

Find my code at: http://github.com/dokterbob/django-agenda

Blog Tags