Natural language parsing of dates and recurring events
Switch branches/tags
Nothing to show
Clone or download
kvh Merge pull request #7 from eyesee1/master
python 3 compatibility
Latest commit 283998f Mar 4, 2017


Recurrent is a python library for natural language parsing of dates and recurring events. It turns strings like "every tuesday and thurs until next month" into RFC-compliant RRULES, to be fed into a calendar api or python-dateutil's rrulestr.

pip install recurrent


Date times

  • next tuesday
  • tomorrow
  • in an hour

Recurring events

  • on weekdays
  • every fourth of the month from jan 1 2010 to dec 25th 2020
  • each thurs until next month
  • once a year on the fourth thursday in november
  • tuesdays and thursdays at 3:15

Messy strings

  • Please schedule the meeting for every other tuesday at noon
  • Set an alarm for next tuesday at 11pm


>>> import datetime
>>> from recurrent import RecurringEvent
>>> r = RecurringEvent(now_date=datetime.datetime(2010, 1, 1))
>>> r.parse('every day starting next tuesday until feb')
>>> r.is_recurring
>>> r.get_params()
{'dtstart': '20100105', 'freq': 'daily', 'interval': 1, 'until': '20100201'}

>>> r.parse('feb 2nd')
datetime.datetime(2010, 2, 2, 0, 0)

>>> r.parse('not a date at all')

You can then use python-dateutil to work with the recurrence rules.

>>> from dateutil import rrule
>>> rr = rrule.rrulestr(r.get_RFC_rrule())
>>> rr.after(datetime.datetime(2010, 1, 2))
datetime.datetime(2010, 1, 5, 0, 0)
>>> rr.after(datetime.datetime(2010, 1, 25))
datetime.datetime(2010, 1, 26, 0, 0)


Recurrent uses parsedatetime to parse dates. If you grab the pypi version of parsedatetime though, some tests in recurrent will fail due to a bug with manually setting the "now" time. For some use cases this won't be an issue, but if you need this functionality before it's patched you can grab my fork of parsedatetime.

Take a look at the tests for more.

Things it can't do

Recurrent is regrettably quite U.S. (and completely english) centric. Contributions from other perspectives are welcome :)


Recurrent is inspired by the similar Ruby library Tickle by Joshua Lippiner. It also uses the parsedatetime library for fuzzy human date parsing.


Ken Van Haren @squaredloss