I was browsing the Daily Python-URL this morning, when I came across a link to a Python module for reading OSX’s iCal files. The module’s web page states:
Apple doesn't document the API for interfacing with iCal, but it does save
it's files as industry standard iCalendar files. I went looking recently
for a python module to interface with iCal, and couldn't find one.
It’s great to have a good Python module to read standard iCalendar files, but the statement that Apple doesn’t have a documented API for interfacing with iCal is bogus. iCal supports the Open Scripting Architecture (AppleScript’s APIs), the same as every other Apple application does. The Open Scripting Architecture can be used from Python much easier than one can read an iCalendar file, and the information is exposed in a very easy to access format. I wrote an earlier article on how to do similar actions with iTunes, so in my continuing effort to educate the world on how to use OSA from Python, here’s some more!
The first step in using iCal from a Python script through OSA is to generate an iCal module which wraps up the low-level OSA details. The gensuitemodule.py script is designed to do just that. It is located in your plat-mac directory inside your Python installation’s lib directory. On a stock installation of Panther, that makes it in /System/Library/Frameworks/Python.framework/ pant,pant Versions/Current/lib/python2.3/plat-mac/gensuitemodule.py. In order to interface with the system window manager and access OSA, it must be run with the pythonw executable, rather than python. The --output command line parameter can be used to specify a name for the output module. In the end, generating the module is extremely simple:
pythonw {...}/gensuitemodule.py --output iCal /Applications/iCal.app
Now that you have a beautiful iCal module, what do you do with it? The iCal.iCal class is the basic application, which is used for all OSA communications with the iCal application itself. So, to start things off, an instance of that class should be created so we can do some communicating:
import iCal
app = iCal.iCal()
How do we determine what we can do to this application through OSA? The easiest way is to use OSX’s Script Editor, which allows us to open up an application’s OSA dictionary and view the contents. The Script Editor is located in the /Applications/AppleScript folder, and has an option in the File menu to Open Dictionary....
Once you have iCal’s dictionary open, inside the iCal suite you can see all the classes and commands that iCal exposes. For example, the application class has elements like calendar, window, and document. Since we’re interested in getting data out, we know that calendar is where we want to start. An element is a collection of objects, implying that each application has a collection of calendars. Based upon what we know of how iCal works, this sounds very reasonable. Here’s how we can iterate over all the calendars that our iCal has:
numCalendars = app.count(app, each=iCal.calendar)
for i in range(1, numCalendars + 1):
cal = iCal.calendar(i)
The first line sends an OSA command to iCal asking it to count the number of iCal.calendar objects it currently has. Since Python normally uses zero-based counting, and OSA uses one-based counting, we need to iterate from 1 to numCalendars + 1. We create an iCal.calendar object from each of those indicies. Creating the object doesn’t do any communication with iCal, it just creates an object which can dispatch calls to the appropriate instance of the calendar class.
What if we wanted to get some data out of the object, now? The Script Editor shows that the calendar objects support a number of properties like tint, title, and description. Let’s print out the title of every calender:
print "Calendar %s - %s" % (i, app.get(cal.title))
The magic here is in the app.get(cal.title). This tells the application to retrieve the title property of the cal instance, which is already bound to the proper calendar object in iCal. We simply print it out, which outputs something like:
Calendar 1 - Home
Calendar 2 - Work
Let’s put these chunks of code together, and include the ability to print out every event for each calendar:
import iCal
def printAllEvents(app, calendar):
numEvents = app.count(calendar, each=iCal.event)
for i in range(1, numEvents + 1):
event = calendar.event(i)
print "\tEvent %s - %s" % (i, app.get(event.summary))
def printAllCalendars(app, eventsToo = True):
numCalendars = app.count(app, each=iCal.calendar)
for i in range(1, numCalendars + 1):
calendar = iCal.calendar(i)
print "Calendar %s - %s" % (i, app.get(calendar.title))
if eventsToo:
printAllEvents(app, calendar)
app = iCal.iCal()
printAllCalendars(app)
Yay! We have access to every piece of information iCal stores, and we didn’t need to parse an iCalendar file. Some parts of iCal even begin to integrate with the OSX Address Book, and we can access that information as well.
One last bit of code could be useful, though. What if we wanted to change some of the data in iCal? It’s fairly simple, but not too obvious or well documented anywhere. Here’s a short snippet that will give all your calendars dumb, pointless names:
import iCal
app = iCal.iCal()
numCalendars = app.count(app, each=iCal.calendar)
for i in range(1, numCalendars + 1):
calendar = iCal.calendar(i)
app.set(calendar.title, to = "Calendar %s" % i)
