Recurring ICal events for Python

ICal has some complexity to it: Events, TODOs and Journal entries 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)
events with multiple RRULE (DONE)
RDATE (DONE)
DURATION (DONE)
EXDATE (DONE)
X-WR-TIMEZONE compatibilty (DONE)
non-gregorian event repetitions (TODO)

Not included:

EXRULE (deprecated), see 8.3.2. Properties Registry

Installation

You can install this package using pip.

pip install 'recurring-ical-events==3.*'

On Debian/Ubuntu, you use the package manager to install python-recurring-ical-events.

sudo apt-get install python-recurring-ical-events

Support

We accept donations to sustain our work, once or regular. Consider donating money to open-source as everyone benefits.

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,) # a year
a_date = (2023, 1) # January in 2023
a_date = (2023, 1, 1) # the 1st of January in 2023
a_date = "20230101"   # 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
a_date = datetime.datetime.now() # this exact second

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). Additionally, the end argument can be a datetime.timedelta to express that the end is relative to the start. For examples of arguments, see at(a_date) above.

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

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

`after(earliest_end)`

You can retrieve events that happen after a time or date using after(earliest_end). Events that are happening during the earliest_end are included in the iteration.

earlierst_end = 2019
for event in recurring_ical_events.of(an_icalendar_object).after(earlierst_end):
    print(event["DTEND"]) # all dates printed are after January 1st 2019

`all()`

If you wish to iterate over all occurrences of the components, then you can use all(). Since a calendar can define a huge amount of recurring entries, this method generates them and forgets them, reducing memory overhead.

This example shows the first event that takes place in the calendar:

query = recurring_ical_events.of(an_icalendar_object)
first_event = next(query.all()) # not all events are generated
print("First event starts at: {first_event}")

`count()`

You can count occurrences of events and other components using count().

number_of_events = recurring_ical_events.of(an_icalendar_object).count()
print(f"{number_of_events} events happen in this calendar.")

number_of_TODOs = recurring_ical_events.of(an_icalendar_object, components=["VTODO"]).count()
print(f"You have {number_of_TODOs} things to do!")

number_of_journal_entries = recurring_ical_events.of(an_icalendar_object, components=["VJOURNAL"]).count()
print(f"There are {number_of_journal_entries} journal entries in the calendar.")

`events` as list - `at()` and `between()`

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. (always present)
DTEND which is the end of the event instance. (always present)
RDATE, EXDATE, RRULE are the rules to create event repetitions. They are not included in repeated events, see Issue 23. To change this, use of(calendar, keep_recurrence_attributes=True).

Generator - `after()` and `all()`

If the resulting components are ordered when after(earliest_end) or all() is used. The result is an iterator that returns the events in order.

for event in recurring_ical_events.of(an_icalendar_object).after(datetime.datetime.now()):
    print(event["DTSTART"]) # The start is ordered

Different Components, not just Events

By default the recurring_ical_events only selects events as the name already implies. However, there are different components available in a calendar. You can select which components you like to have returned by passing components to the of function:

of(a_calendar, components=["VEVENT"])

Here is a template code for choosing the supported types of components:

events = recurring_ical_events.of(calendar).between(...)
journals = recurring_ical_events.of(calendar, components=["VJOURNAL"]).between(...)
todos = recurring_ical_events.of(calendar, components=["VTODO"]).between(...)
all = recurring_ical_events.of(calendar, components=["VTODO", "VEVENT", "VJOURNAL"]).between(...)

If a type of component is not listed here, it can be added. Please create an issue for this in the source code repository.

Speed

If you use between() or at() several times, it is faster to re-use the object coming from of().

rcalendar = recurring_ical_events.of(an_icalendar_object)
events_of_day_1 = rcalendar.at(day_1)
events_of_day_2 = rcalendar.at(day_2)
events_of_day_3 = rcalendar.at(day_3)
# ...

Skip bad formatted ical events

Some events may be badly formatted and therefore cannot be handled by recurring-ical-events. Passing skip_bad_series=True as of() argument will totally skip theses events.

of(a_calendar, skip_bad_series=True)

Version Fixing

If you use this library in your code, you may want to make sure that updates can be received but they do not break your code. The version numbers are handeled this way: a.b.c example: 0.1.12

c is changed for each minor bug fix.
b is changed whenever new features are added.
a is changed when the interface or major assumptions change that may break your code.

So, I recommend to version-fix this library to stay with the same a while b and c can change.

Development

Code style

Please install pre-commit before git commit. It will ensure that the code is formatted and linted as expected using ruff.

pre-commit install

Testing

This project's development is driven by tests. Tests assure a consistent interface and less knowledge lost over time. If you like to change the code, tests help that nothing breaks in the future. They are required in that sense. Example code and ics files can be transferred into tests and speed up fixing bugs.

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.

To run the tests, we use tox. tox tests all different Python versions which we want to be compatible to.

pip3 install tox

To run all the tests:

tox

To run the tests in a specific Python version:

tox -e py39

New Releases

To release new versions,

edit the Changelog Section
edit setup.py, the __version__ variable
create a commit and push it
wait for GitHub Actions to finish the build
run
```
python3 setup.py tag_and_deploy
```
notify the issues about their release

Architecture

Each icalendar Calendar can contain Events, Journal entries, TODOs and others, called Components. Those entries are grouped by their UID. Such a UID defines a Series of Occurrences that take place at a given time. Since each Component is different, the ComponentAdapter offers a unified interface to interact with them. The Calendar gets filtered and for each UID, a Series can use one or more ComponentAdapters to create Occurrences of what happens in a time span. These Occurrences are used internally and convert to Components for further use.

Changelog

v3.2.0
- Allow datetime.timedelta as second argument to between(absolute_time, datetime.timedelta())
v3.1.1
- Fix: Remove duplication of modification with same sequence number, see Issue 164
- Fix: EXDATE now excludes a modified instance for an event with higher SEQUENCE, see Issue
v3.1.0
- Add count() -> int to count all occurrences within a calendar
- Add all() -> Generator[icalendar.Component] to iterate over the whole calendar
v3.0.0
- Change the architecture and add a diagram
- Add type hints, see Issue 91
- Rename UnfoldableCalendar to CalendarQuery
- Rename of(skip_bad_events=None) to of(skip_bad_series=False)
- of(components=[...]) now also takes ComponentAdapters
- Fix edit sequence problems, see Issue 151
v2.2.3
- Fix: Edits of whole event are now considering RDATE and EXDATE, see Issue 148
v2.2.2
- Test support for icalendar==6.*
- Remove Python 3.7 from tests and compatibility list
- Remove pytz from requirements
v2.2.1
- Add support for multiple RRULE in events.
v2.2.0
- Add after() method to iterate over upcoming events.
v2.1.3
- Test and support Python 3.12.
- Change SPDX license header.
- Fix RRULE with negative COUNT, see Issue 128
v2.1.2
- Fix RRULE with EXDATE as DATE, see PR 121 by Jan Grasnick and PR 122.
v2.1.1
- Claim and test support for Python 3.11.
- Support deleting events by setting RRULE UNTIL < DTSTART, see Issue 117.
v2.1.0
- Added support for PERIOD values in RDATE. See Issue 113.
- Fixed icalendar>=5.0.9 to support RDATE of type PERIOD with a time zone.
- Fixed pytz>=2023.3 to assure compatibility.
v2.0.2
- Fixed omitting last event of RRULE with UNTIL when using pytz, the event starting in winter time and ending in summer time. See Issue 107.
v2.0.1
- Fixed crasher with duplicate RRULE. See Pull Request 104
v2.0.0b
- Only return VEVENT by default. Add of(... ,components=...) parameter to select which kinds of components should be returned. See Issue 101.
- Remove beta indicator. This library works okay: Feature requests come in, not so much bug reports.
v1.1.0b
- Add repeated TODOs and Journals. See Pull Request 100 and Issue 97.
v1.0.3b
- Remove syntax anomalies in README.
- Switch to GitHub actions because GitLab decided to remove support.
v1.0.2b
- Add support for X-WR-TIMEZONE calendars which contain events without an explicit time zone, see Issue 86.
v1.0.1b
- Add support for zoneinfo.ZoneInfo time zones, see Issue 57.
- Migrate from Travis CI to Gitlab CI.
- Add code coverage on Gitlab.
v1.0.0b
- Remove Python 2 support, see Issue 64.
- Remove support for Python 3.5 and 3.6.
- Note: These deprecated Python versions may still work. We just do not claim they do.
- X-WR-TIMEZONE support, see Issue 71.
v0.2.4b
- Events with a duration of 0 seconds are correctly returned.
- between() and at() take the same kind of arguments. These arguments are documented.
v0.2.3b
- between() and at() allow arguments with time zones now when calendar events do not have time zones, reported in Issue 61 and Issue 52.
v0.2.2b
- Check that at() does not return an event starting at the next day, see Issue 44.
v0.2.1b
- Check that recurring events are removed if they are modified to leave the requested time span, see Issue 62.
v0.2.0b
- Add ability to keep the recurrence attributes (RRULE, RDATE, EXDATE) on the event copies instead of stripping them. See Pull Request 54.
v0.1.21b
- Fix issue with repetitions over DST boundary. See Issue 48.
v0.1.20b
- Fix handling of modified recurrences with lower sequence number than their base event Pull Request 45
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

python-dateutil - to compute the recurrences of events using rrule
icalendar - the library used to parse ICS files
pytz - for timezones
x-wr-timezone for handling the non-standard X-WR-TIMEZONE property.

Related Projects

icalevents - another library for roughly the same use-case
Open Web Calendar - a web calendar to embed into websites which uses this library
icspy - to create your own calendar events
pyICSParser - parse icalendar files and return event times (GitHub)

Media

Nicco Kunzmann talked about this library at the FOSSASIA 2022 Summit:

Talk about this library at the FOSSASIA 2022 Summit

Research

RFC 5545
RFC 7986 -- an update to RFC 5545. It does not change any properties useful for scheduling events.
Stackoverflow question this is created for
https://github.com/oberron/annum
- https://stackoverflow.com/questions/28829261/python-ical-get-events-for-a-day-including-recurring-ones#28829401
https://stackoverflow.com/questions/20268204/ical-get-date-from-recurring-event-by-rrule-and-dtstart
collective/icalendar#162
https://stackoverflow.com/questions/46471852/ical-parsing-reoccuring-events-in-python
RDATE https://stackoverflow.com/a/46709850/1320237
- https://tools.ietf.org/html/rfc5545#section-3.8.5.2

Name		Name	Last commit message	Last commit date
Latest commit History 577 Commits
.github		.github
benchmark		benchmark
img		img
test		test
.cleanup-branches.sh		.cleanup-branches.sh
.gitignore		.gitignore
.gitlab-ci.yml		.gitlab-ci.yml
.pre-commit-config.yaml		.pre-commit-config.yaml
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
README.rst		README.rst
example.py		example.py
pyproject.toml		pyproject.toml
recurring_ical_events.py		recurring_ical_events.py
requirements.txt		requirements.txt
setup.py		setup.py
test-requirements.txt		test-requirements.txt
tox.ini		tox.ini

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

Recurring ICal events for Python

Installation

Support

Example

Usage

`at(a_date)`

`between(start, end)`

`after(earliest_end)`

`all()`

`count()`

`events` as list - `at()` and `between()`

Generator - `after()` and `all()`

Different Components, not just Events

Speed

Skip bad formatted ical events

Version Fixing

Development

Code style

Testing

New Releases

Architecture

Changelog

Libraries Used

Related Projects

Media

Research

About

Releases

Packages

Languages

License

HESPUL/python-recurring-ical-events

Folders and files

Latest commit

History

Repository files navigation

Recurring ICal events for Python

Installation

Support

Example

Usage

at(a_date)

between(start, end)

after(earliest_end)

all()

count()

events as list - at() and between()

Generator - after() and all()

Different Components, not just Events

Speed

Skip bad formatted ical events

Version Fixing

Development

Code style

Testing

New Releases

Architecture

Changelog

Libraries Used

Related Projects

Media

Research

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

`at(a_date)`

`between(start, end)`

`after(earliest_end)`

`all()`

`count()`

`events` as list - `at()` and `between()`

Generator - `after()` and `all()`

Packages