Skip to main content

A Python module which repeats ICalendar events by RRULE, RDATE and EXDATE.

Project description

Travis Build and Tests Status Python Package Version on Pypi Downloads from Pypi

ICal has some complexity to it: Events can be repeated, removed from the feed and edited later on. This tool takes care of these circumstances.

Let’s put our expertise together and build a tool that can solve this!

  • day light saving time (DONE)
  • recurring events (DONE)
  • recurring events with edits (DONE)
  • recurring events where events are omitted (DONE)
  • recurring events events where the edit took place later (DONE)
  • normal events (DONE)
  • recurrence of dates but not hours, minutes, and smaller (DONE)
  • endless recurrence (DONE)
  • ending recurrence (DONE)
  • events with start date and no end date (DONE)
  • events with start as date and start as datetime (DONE)
  • RRULE (DONE)
  • RDATE (DONE)
  • DURATION (DONE)
  • EXDATE (DONE)

Not included:

Installation

pip install recurring-ical-events

Example

import icalendar
import recurring_ical_events
import urllib.request

start_date = (2019, 3, 5)
end_date =   (2019, 4, 1)
url = "http://tinyurl.com/y24m3r8f"

ical_string = urllib.request.urlopen(url).read()
calendar = icalendar.Calendar.from_ical(ical_string)
events = recurring_ical_events.of(calendar).between(start_date, end_date)
for event in events:
    start = event["DTSTART"].dt
    duration = event["DTEND"].dt - event["DTSTART"].dt
    print("start {} duration {}".format(start, duration))

Output:

start 2019-03-18 04:00:00+01:00 duration 1:00:00
start 2019-03-20 04:00:00+01:00 duration 1:00:00
start 2019-03-19 04:00:00+01:00 duration 1:00:00
start 2019-03-07 02:00:00+01:00 duration 1:00:00
start 2019-03-08 01:00:00+01:00 duration 2:00:00
start 2019-03-09 03:00:00+01:00 duration 0:30:00
start 2019-03-10 duration 1 day, 0:00:00

Usage

The icalendar module is responsible for parsing and converting calendars. The recurring_ical_events module uses such a calendar and creates all repetitions of its events within a time span.

To import this module, write

import recurring_ical_events

There are several methods you can use to unfold repeating events, such as at(a_time) and between(a_start, an_end).

at(a_date)

You can get all events which take place at a_date. A date can be a year, e.g. 2023, a month of a year e.g. January in 2023 (2023, 1), a day of a certain month e.g. (2023, 1, 1), an hour e.g. (2023, 1, 1, 0), a minute e.g. (2023, 1, 1, 0, 0), or second as well as a datetime.date object and datetime.datetime.

The start and end are inclusive. As an example: if an event is longer than one day it is still included if it takes place at a_date.

a_date = 2023 # a year
a_date = (2023, 1) # January in 2023
a_date = (2023, 1, 1) # the 1st of January in 2023
a_date = (2023, 1, 1, 0) # the first hour of the year 2023
a_date = (2023, 1, 1, 0, 0) # the first minute in 2023
a_date = datetime.date(2023) # the first day in 2023
a_date = datetime.date(2023, 1, 1) # the first day in 2023

events = recurring_ical_events.of(an_icalendar_object).at(a_date)

The resulting events are a list of icalendar events, see below.

between(start, end)

between(start, end) returns all events happening between a start and an end time. Both arguments can be datetime.datetime, datetime.date, tuples of numbers passed as arguments to datetime.datetime or strings in the form of %Y%m%d (yyyymmdd) and %Y%m%dT%H%M%SZ (yyyymmddThhmmssZ). For examples, see at(a_date) above.

events = recurring_ical_events.of(an_icalendar_object).between(start, end)

The resulting events are in a list, see below.

events as list

The result of both between(start, end) and at(a_date) is a list of icalendar events. By default, all attributes of the event with repetitions are copied, like UID and SUMMARY. However, these attributes may differ from the source event:

  • DTSTART which is the start of the event instance.
  • DTEND which is the end of the event instance.
  • RDATE, EXDATE, RRULE are the rules to create event repetitions. They are not included in repeated events, see Issue 23.

Development

  1. Optional: Install virtualenv and Python3 and create a virtual environment.
    virtualenv -p python3 ENV
    source ENV/bin/activate
    
  2. Install the packages.
    pip install -r requirements.txt -r test-requirements.txt
    
  3. Run the tests
    pytest
    

To release new versions,

  1. edit the Changelog Section

  2. edit setup.py, the __version__ variable

  3. create a commit and push it

  4. run
    python3 setup.py tag_and_deploy
    
  5. notify the issues about their release

Testing

This project’s development is driven by tests. You can view the tests in the test folder. If you have a calendar ICS file for which this library does not generate the desired output, you can add it to the test/calendars folder and write tests for what you expect. If you like, open an issue first, e.g. to discuss the changes and how to go about it.

Changelog

  • v0.1.19b
    • Benchmark using @mrx23dot’s script and speed up recurrence calculation by factor 4, see Issue 42.
  • v0.1.18b
    • Handle Issue 28 so that EXDATEs match as expected.
    • Handle Issue 27 so that parsing some rrule UNTIL values does not crash.
  • v0.1.17b
    • Handle Issue 28 where passed arguments lead to errors where it is expected to work.
  • v0.1.16b
    • Events with an empty RRULE are handled like events without an RRULE.
    • Remove fixed dependency versions, see Issue 14
  • v0.1.15b
    • Repeated events also include subcomponents. Issue 6
  • v0.1.14b
    • Fix compatibility issue 20: EXDATEs of different time zones are now supported.
  • v0.1.13b
    • Remove attributes RDATE, EXDATE, RRULE from repeated events Issue 23
    • Use vDDDTypes instead of explicit date/datetime type Pull Request 19
    • Start Changelog

Libraries Used

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for recurring-ical-events, version 0.1.19b0
Filename, size File type Python version Upload date Hashes
Filename, size recurring_ical_events-0.1.19b0.tar.gz (26.7 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page