Pycalcal — Calendrical Calculations in Python

View the Project on GitHub espinielli/pycalcal

PyCalCal is a Python library that makes it easy to:

You can also try it out online (experimental !!)

How to run PyCalCal

In order to use the pycalcal you need:

Then it is enough to place file in any place where python can load it, i.e. your current working directory.

Getting started

The first thing to do is to load pycalcal. From your python prompt type (omit >>> of course...)

>>> import pycalcal as pcc

You are now ready to play with calendars, i.e. converting dates from gregorian to coptic:

>>> fix = pcc.fixed_from_gregorian(pcc.gregorian_date(2006, 2, 5))
>>> pcc.coptic_from_fixed(fix)
[1722, 5, 28]

or finding out when next year's Easter will be

>>> pcc.gregorian_from_fixed(pcc.easter(2010))
[20010, 4, 4]

or Hindu's New Year for 2009:

>>> pcc.gregorian_from_fixed(pcc.diwali(2009)[0])
[2009, 10, 19]


How to build PyCalCal

PyCalCal is generated following the literate programming paradigm. In order generate source code and documentation you need the following tools:

Unit tests' line coverage metrics are gathered by coverage

Here are the steps for buiding:

  1. execute in order to create the Makefile

    $ ./

  2. generate the code:

    $ make

  3. generate the doc:

    $ make figures $ make pycalcal.pdf

  4. run the tests:

    $ make test


PyCalCal is an implementation in Python of CALENDRICA 3.0, which is the Common Lisp implementation of the functions described in the book

Nachum Dershowitz, Edward M. Reingold "Calendrical Calculations"
Cambridge University Press; 3rd edition (December 10, 2007)
Paperback; ISBN-13: 9780521702386
E. M. Reingold and N. Dershowitz,
3rd ed., Cambridge University Press, 2008.

Some of the algorithms are from:

Jean Meeus "Astronomical Algorithms"
Willmann-Bell, Inc.
2nd edition (1998 with corrections as of June 15, 2005);
ISBN: 0-943396-61-1


I, Enrico Spinielli, implemented PyCalCal for fun and to further assaporate the beauty of the work of the authors of the book. Having said so, PyCalCal code is pretty well tested and usable.

See 'STATUS' file for further details.


I want to thank:


CALENDRICAL 3.0 is written and copyrighted by E. M. Reingold and N. Dershowitz as described in file 'COPYRIGHT_DERSHOWITZ_REINGOLD'


Prof. Reingold mantains a companion site for the book.

The resource page of the book at Cambridge University Press provides a link to a zipped version of '' which I included unzipped in PyCalCal project repo in order to be able to reference the relevant snippets of the original implementation.

Files 'dates[1-5].tex', containing test data, have been kindly provided to me by Prof. Reingold.