Run update-copyright.py

[pycalendar.git] / README

Flexible aggregation for iCalendar feeds (`RFC 5545`_).

The iCalender standard provides a common format for exchanging
calendar information.  This project aims to provide a library with a
clean API for aggregating and processing iCalendar feeds.  What you do
with that processed information is up to you.

There are a number of existing aggregators, ranging from the
closed-source `Google Calendar`_ to the open-source elmcity_ and
Calagator_.  However, I want a library that can work as an iCalendar
version of feedparser_, and `code for a web-frontend`__ is just dead
weight.  It turns out that elmcity uses the icalendar_ parsing
library, and there are a number of other pre-existing libraries:

icalendar_:
  A parsing library for Python 2.6 and 2.7 that spun off from Plone_.
RDFCalendar_:
  A tool for converting between iCalendars and RDF.
Py-Calendar_:
  A sparsely documented library.  There's a lot of code in here, but I
  think it reproduces a lot of stuff that could be borrowed from the
  standard library.
pyICSParser_:
  Another sparsely documented library.  Again, there's a lot of code
  in here, but I think there's too much local code.
PyCal_:
  A (dead?) package.  The PyPI links don't go anywhere.

Installation
============

Pycalendar is packaged with distutils_, so you can install it in all
the usual ways.  Any of the following should work::

  $ python setup.py install
  $ pip install pycalendar

The only dependency outside Python's standard library is pytz_.

Testing
=======

Test with nose_::

  $ nosetests --with-doctest --doctest-tests pycalendar

There is also a example aggregation script that prints aggregate feed
to stdout and geographic positions to stderr.  Run it with::

  $ PYTHONPATH=. test/aggregate.py


.. _Calagator: http://calagator.org/
.. _distutils: http://docs.python.org/3/distutils/
.. _elmcity: http://elmcity.cloudapp.net/
.. _elmcity code: https://github.com/judell/elmcity
.. _feedparser: https://pypi.python.org/pypi/feedparser/
.. _Google Calendar: https://support.google.com/calendar/
.. _icalendar: http://icalendar.readthedocs.org/en/latest/
.. _nose: https://nose.readthedocs.org/en/latest/
.. _Plone: http://plone.org/
.. _Py-Calendar: https://pypi.python.org/pypi/Py-Calendar
.. _PyCal: https://pypi.python.org/pypi/PyCal
.. _pyICSParser: https://pypi.python.org/pypi/pyICSParser
.. _pytz: https://pypi.python.org/pypi/pytz/
.. _RDFCalendar: https://pypi.python.org/pypi/RDFCalendar

.. _RFC 5545: http://tools.ietf.org/html/rfc5545