How to#

Additionally to the examples listed here, you can have a look the API documentation. In the Media Section, you can videos and useful information on social media.

Read a file and print events#

The following example loads a calendar from a file and prints the events happening between the 1st of January 2017 and the 1st of January 2018.

>>> import icalendar
>>> import recurring_ical_events
>>> from pathlib import Path

# read the calendar file and parse it
# CALENDARS = Path("to/your/calendar/directory")
>>> calendar_file : Path = CALENDARS / "fablab_cottbus.ics"
>>> ical_string = calendar_file.read_bytes()
>>> print(ical_string[:28])
BEGIN:VCALENDAR
VERSION:2.0
>>> a_calendar = icalendar.Calendar.from_ical(ical_string)

# request the events in a specific interval
# start on the 1st of January 2017 0:00
>>> start_date = (2017, 1, 1)

# the event on the 1st of January 2018 is not included
>>> end_date =   (2018,  1, 1)
>>> events = recurring_ical_events.of(a_calendar).between(start_date, end_date)
>>> for event in events:
...     start = event["DTSTART"].dt
...     summary = event["SUMMARY"]
...     print(f"start {start} summary {summary}")
start 2017-03-11 17:00:00+01:00 summary Vereinssitzung
start 2017-06-10 10:00:00+02:00 summary Repair und Recycling Café
start 2017-06-11 16:30:00+02:00 summary Brandenburger Maker-Treffen
start 2017-07-05 17:45:00+02:00 summary Der Computer-Treff fällt aus
start 2017-07-29 14:00:00+02:00 summary Sommerfest
start 2017-10-19 16:00:00+02:00 summary 3D-Modelle programmieren mit OpenSCAD
start 2017-10-20 16:00:00+02:00 summary Programmier dir deine eigene Crypto-Währung
start 2017-10-21 13:00:00+02:00 summary Programmiere deine eigene Wetterstation
start 2017-10-22 13:00:00+02:00 summary Luftqualität: Ein Workshop zum selber messen (Einsteiger)
start 2017-10-22 13:00:00+02:00 summary Websites selbst programmieren

List events at certain a time#

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.

>>> import datetime

# save the query object for the calendar
>>> query = recurring_ical_events.of(a_calendar)
>>> len(query.at(2023))                      # a year - 2023 has 12 events happening
12
>>> len(query.at((2023,)))                   # a year
12
>>> len(query.at((2023, 1)))                 # January in 2023 - only one event is in January
1
>>> len(query.at((2023, 1, 1)))              # the 1st of January in 2023
0
>>> len(query.at("20230101"))                # the 1st of January in 2023
0
>>> len(query.at((2023, 1, 1, 0)))           # the first hour of the year 2023
0
>>> len(query.at((2023, 1, 1, 0, 0)))        # the first minute in 2023
0
>>> len(query.at(datetime.date(2023, 1, 1))) # the first day in 2023
0

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

List events within a time range#

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.

>>> query = recurring_ical_events.of(a_calendar)

# What happens in 2016, 2017 and 2018?
>>> events = recurring_ical_events.of(a_calendar).between(2016, 2019)
>>> len(events) # quite a lot is happening!
39

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

List events after a certain time#

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 = 2023
>>> for i, event in enumerate(query.after(earlierst_end)):
...     print(f"{event['SUMMARY']} ends {event['DTEND'].dt}") # all dates printed are after January 1st 2023
...     if i > 10: break  # we might get endless events and a lot of them!
Repair Café ends 2023-01-07 17:00:00+01:00
Repair Café ends 2023-02-04 17:00:00+01:00
Repair Café ends 2023-03-04 17:00:00+01:00
Repair Café ends 2023-04-01 17:00:00+02:00
Repair Café ends 2023-05-06 17:00:00+02:00
Repair Café ends 2023-06-03 17:00:00+02:00
Repair Café ends 2023-07-01 17:00:00+02:00
Repair Café ends 2023-08-05 17:00:00+02:00
Repair Café ends 2023-09-02 17:00:00+02:00
Repair Café ends 2023-10-07 17:00:00+02:00
Repair Café ends 2023-11-04 17:00:00+01:00
Repair Café ends 2023-12-02 17:00:00+01:00

List all events#

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:

>>> first_event = next(query.all()) # not all events are generated
>>> print(f"The first event is {first_event['SUMMARY']}")
The first event is Weihnachts Repair-Café

Count events#

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

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

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

However, this can be very costly!

Split a query into pages#

Pagination allows you to chop the resulting components into chunks of a certain size.

# we get a calendar with 10 events and 2 events per page
>>> ten_events = recurring_ical_events.example_calendar("event_10_times")
>>> pages = recurring_ical_events.of(ten_events).paginate(2)

# we can iterate over the pages with 2 events each
>>> for i, last_page in enumerate(pages):
...     print(f"page: {i}")
...     for event in last_page:
...         print(f"->  {event.start}")
...     if i == 1: break
page: 0
->  2020-01-13 07:45:00+01:00
->  2020-01-14 07:45:00+01:00
page: 1
->  2020-01-15 07:45:00+01:00
->  2020-01-16 07:45:00+01:00

If you run a web service and you would like to continue pagination after a certain page, this can be done, too. Just hand someone the next_page_id and continue from there on.

# resume the same query from the next page
>>> pages = recurring_ical_events.of(ten_events).paginate(2, next_page_id = last_page.next_page_id)
>>> for i, last_page in enumerate(pages):
...     print(f"page: {i + 2}")
...     for event in last_page:
...         print(f"->  {event.start}")
...     if i == 1: break
page: 2
->  2020-01-17 07:45:00+01:00
->  2020-01-18 07:45:00+01:00
page: 3
->  2020-01-19 07:45:00+01:00
->  2020-01-20 07:45:00+01:00

The last_page.next_page_id is a string so that it can be used easily. It is tested against malicious modification and can safely be passed from a third party source.

Additionally to the page size, you can also pass a start and an end to the pages so that all components are visible within that time.

Get Todos and Journal entries#

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:

>>> query_events = recurring_ical_events.of(a_calendar)
>>> query_journals = recurring_ical_events.of(a_calendar, components=["VJOURNAL"])
>>> query_todos = recurring_ical_events.of(a_calendar, components=["VTODO"])
>>> query_all = recurring_ical_events.of(a_calendar, components=["VTODO", "VEVENT", "VJOURNAL"])

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

For further customization, please refer to the section on how to extend the default functionality.

Calculate Alarm times#

Alarms are subcomponents of events and todos. They only make sense with an event or todo. Thus the interface is slightly different.

Add VALARM as the component you would like:

>>> query_alarms = recurring_ical_events.of(a_calendar, components=["VALARM"])

In the following example, an event has an alarm one week before it starts. The component returned is not a VALARM component but instead the VEVENT with only one VALARM in it.

# read an .ics file with an event with an alarm
>>> calendar_with_alarm = recurring_ical_events.example_calendar("alarm_1_week_before_event")
>>> alarm_day = datetime.date(2024, 12, 2)

# we get the event that has an alarm on that day
>>> event = recurring_ical_events.of(calendar_with_alarm, components=["VALARM"]).at(alarm_day)[0]
>>> len(event.alarms.times)
1
>>> alarm = event.alarms.times[0]

# the alarm happens one week before the event
>>> event.start - alarm.trigger
datetime.timedelta(days=7)

In the following code, we query the same day for a VEVENT component and we find nothing. The event happens a week later.

# No events on that day. There is only an alarm.
>>> recurring_ical_events.of(calendar_with_alarm, components=["VEVENT"]).at(alarm_day)
[]

When querying events and todos, they keep their alarms and other subcompnents. These alarm times can be outside of the dates requested.

In this example, we get an event and find that it has several alarms in it.

>>> event_day = alarm_day + datetime.timedelta(days=7)
>>> event = recurring_ical_events.of(calendar_with_alarm, components=["VEVENT"]).at(event_day)[0]

# The event a week later has more than one alarm.
>>> len(event.walk("VALARM"))
2

Edit one event of an existing series#

Editing one event of a series is necessary for calendar invites e.g. via email.

Below, you see how to edit an event that occurs in a series. It is important that you increase the sequence number of the event to indicate the new version.

>>> calendar = recurring_ical_events.example_calendar("recurring_events_moved")
>>> event = recurring_ical_events.of(calendar).at("20190309")[0]

# This event happens on 2019-03-09.
>>> print(event["SUMMARY"])
New Event

# The event can be modified.
>>> event["SUMMARY"] = "Modified Again!"

# Make sure to increase the sequence number!
# If you do not do that, the modification will not appear.
>>> event["SEQUENCE"] = event.get("SEQUENCE", 0) + 1

# Add the modified event to the calendar to replace the original.
>>> calendar.add_component(event)

# Get the day again and see the modified event.
>>> event = recurring_ical_events.of(calendar).at("20190309")[0]
>>> print(event["SUMMARY"])
Modified Again!

Extend recurring-ical-events#

All the functionality of recurring-ical-events can be extended and modified. To understand where to extend, have a look at the Architecture.

The first place for extending is the collection of components. Components are collected into a Series. A series belongs together because all components have the same UID. In this example, we collect one VEVENT which matches a certain UID:

>>> from recurring_ical_events import SelectComponents, EventAdapter, Series
>>> from icalendar.cal import Component
>>> from typing import Sequence

# create the calendar
>>> calendar_file = CALENDARS / "machbar_16_feb_2019.ics"
>>> machbar_calendar = icalendar.Calendar.from_ical(calendar_file.read_bytes())

# Create a collector of components that searches for an event with a specific UID
>>> class CollectOneUIDEvent(SelectComponents):
...     def __init__(self, uid:str) -> None:
...         self.uid = uid
...     def collect_series_from(self, source: Component, suppress_errors: tuple) -> Sequence[Series]:
...         components : list[Component] = []
...         for component in source.walk("VEVENT"):
...             if component.get("UID") == self.uid:
...                 components.append(EventAdapter(component))
...         return [Series(components)] if components else []

# collect only one UID: 4mm2ak3in2j3pllqdk1ubtbp9p@google.com
>>> one_uid = CollectOneUIDEvent("4mm2ak3in2j3pllqdk1ubtbp9p@google.com")
>>> uid_query = recurring_ical_events.of(machbar_calendar, components=[one_uid])
>>> uid_query.count()  # the event has no recurrence and thus there is only one
1

Several ways of extending the functionality have been created to override internals. These can be subclassed or composed.

Below, you can choose to collect all components. Subclasses can be created for the Series and the Occurrence.

>>> from recurring_ical_events import AllKnownComponents, Series, Occurrence

# we create a calendar with one event
>>> calendar_file = CALENDARS / "one_event.ics"
>>> one_event = icalendar.Calendar.from_ical(calendar_file.read_bytes())

# You can override the Occurrence and Series classes for all computable components
>>> select_all_known = AllKnownComponents(series=Series, occurrence=Occurrence)
>>> select_all_known.names  # these are the supported types of components
['VALARM', 'VEVENT', 'VJOURNAL', 'VTODO']
>>> query_all_known = recurring_ical_events.of(one_event, components=[select_all_known])

# There should be exactly one event.
>>> query_all_known.count()
1

This example shows that the behavior for specific types of components can be extended. Additional to the series, you can change the ComponentAdapter that provides a unified interface for all the components with the same name (VEVENT for example).

>>> from recurring_ical_events import ComponentsWithName, EventAdapter, JournalAdapter, TodoAdapter

# You can also choose to select only specific subcomponents by their name.
# The default arguments are added to show the extensibility.
>>> select_events =   ComponentsWithName("VEVENT",   adapter=EventAdapter,   series=Series, occurrence=Occurrence)
>>> select_todos =    ComponentsWithName("VTODO",    adapter=TodoAdapter,    series=Series, occurrence=Occurrence)
>>> select_journals = ComponentsWithName("VJOURNAL", adapter=JournalAdapter, series=Series, occurrence=Occurrence)

# There should be one event happening and nothing else
>>> recurring_ical_events.of(one_event, components=[select_events]).count()
1
>>> recurring_ical_events.of(one_event, components=[select_todos]).count()
0
>>> recurring_ical_events.of(one_event, components=[select_journals]).count()
0

So, if you would like to modify all events that are returned by the query, you can do that subclassing the Occurrence class.

# This occurence changes adds a new attribute to the resulting events
>>> class MyOccurrence(Occurrence):
...     """An occurrence that modifies the component."""
...     def as_component(self, keep_recurrence_attributes: bool) -> Component:
...         """Return a shallow copy of the source component and modify some attributes."""
...         component = super().as_component(keep_recurrence_attributes)
...         component["X-MY-ATTRIBUTE"] = "my occurrence"
...         return component
>>> query = recurring_ical_events.of(one_event, components=[ComponentsWithName("VEVENT", occurrence=MyOccurrence)])
>>> event = next(query.all())
>>> event["X-MY-ATTRIBUTE"]
'my occurrence'

This library allows extension of functionality during the selection of components to calculate using these classes:

  • ComponentsWithName - for components of a certain name

  • AllKnownComponents - for all components known

  • SelectComponents - the interface to provide

You can further customize behaviour by subclassing these:

  • ComponentAdapter such as EventAdapter, JournalAdapter or TodoAdapter.

  • Series

  • Occurrence

  • CalendarQuery

Increase Performance#

If you use recurring_ical_events.CalendarQuery.between() and other queries several times, it is faster to re-use the object coming from recurring_ical_events.of().

>>> query = recurring_ical_events.of(a_calendar)
>>> events_of_day_1 = query.at((2019, 2, 1))
>>> events_of_day_2 = query.at((2019, 2, 2))
>>> events_of_day_3 = query.at((2019, 2, 3))

# ... and so on

Skip badly 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.

# Create a calendar that contains broken events.
>>> calendar_file = CALENDARS / "bad_rrule_missing_until_event.ics"
>>> calendar_with_bad_event = icalendar.Calendar.from_ical(calendar_file.read_bytes())

 # By default, broken events result in errors.
>>> recurring_ical_events.of(calendar_with_bad_event, skip_bad_series=False).count()
Traceback (most recent call last):
  ...
recurring_ical_events.errors.BadRuleStringFormat: UNTIL parameter is missing: FREQ=WEEKLY;BYDAY=TH;WKST=SU;UNTL=20191023

# With skip_bad_series=True we skip the series that we cannot handle.
>>> recurring_ical_events.of(calendar_with_bad_event, skip_bad_series=True).count()
0