ics.py Documentation

ics.py is a Pythonic iCalendar library designed to read and write .ics data following the RFC5545 specification. It is intended for developers who want a user-friendly way to handle iCalendar data without manually managing the complexities of the specification.

Requirements:

• Python 3.6 or higher

To begin using the library, you should follow the installation and quickstart guides to set up your environment and create your first calendar.

Currently, ics.py does not support the RRULE property. This means:

• It cannot parse the RRULE property from input files.
• It cannot use recurrence rules within the ics.timeline.Timeline class.

Support for RRULE is planned for a future version (expected before version 1.0).

In ics.py, equality (==) and ordering (<, >) use different logic and different sets of attributes:

1. Equality (==, !=): Uses all public attributes of the class. It is strict and requires the objects to be of the same class.
2. Ordering (<, >, etc.): Uses a subset of attributes via a cmp_tuple(). For an Event, this is (begin, end, summary).

Warning: Because ordering only looks at a subset of attributes, the ordering is not total. For example, (x <= y and not x < y) does not necessarily imply x == y, because x and y might differ in attributes that are ignored by the ordering logic (like uid or location).

ics.py does not support the full RFC 5545 specification and may not recognize all custom or extension properties used by various iCalendar creators.

However, ics.py can still read RFC-compliant files containing unknown properties and can output files with specific properties even if it does not understand their meaning. To work with unsupported properties, you should use the low-level API as described in the Advanced guide.

When you deserialize an .ics file, the resulting tzinfo objects might not be identical to the original Python tzinfo objects (e.g., a dateutil object vs. an ics.py Timezone object). However, the datetime objects themselves will still compare as equal if they represent the same instant in UTC.

# e1 is original, e2 is deserialized from e1's serialization
e1_begin = e.begin
e2_begin = e2.begin

# The tzinfo objects are different
e1_begin.tzinfo == e2_begin.tzinfo  # False

# The datetimes represent the same instant
e1_begin == e2_begin  # True

e2 = Calendar(Calendar(events=[e]).serialize()).events[0]

# the tzinfo objects are different
e.begin.tzinfo == e2.begin.tzinfo
# False

# but the datetimes still compare equal
e.begin == e2.begin
# True

To create a new calendar, import Calendar and Event from ics. You can define event properties like summary, description, begin, and end using standard Python datetime objects. Add the event to the calendar's events list and use the serialize() method to generate the iCalendar string for writing to a file.

from datetime import datetime
from ics import Calendar, Event

c = Calendar()
e = Event()
e.summary = "My cool event"
e.description = "A meaningful description"
e.begin = datetime.fromisoformat("2022-06-06T12:05:23+02:00")
e.end = datetime.fromisoformat("2022-06-06T13:05:23+02:00")
c.events.append(e)

# Serialize and write to a file
with open("my.ics", "w", newline='') as f:
    f.write(c.serialize())

A Calendar object represents a unique RFC 5545 iCalendar and can contain Event, Todo, and Timeline iterators. Time and date are handled using standard Python datetime objects. You can add events to a calendar by appending an Event instance to the c.events list.

from datetime import datetime, timezone, timedelta
from ics import Calendar, Event

c = Calendar()
e = Event()
e.summary = "My cool event"
e.description = "A meaningful description"
e.begin = datetime.fromisoformat("2022-06-06T12:05:23+02:00")
e.end = datetime(
    year=2022,
    month=6,
    day=6,
    hour=12,
    minute=5,
    second=23,
    tzinfo=timezone(timedelta(seconds=7200)),
)
c.events.append(e)

Thunderbird is available for most Linux distributions via system package managers. You will need root/administrator privileges to install it.

Use the command corresponding to your distribution:

# Debian/Ubuntu
sudo apt-get update
sudo apt-get install thunderbird

# Fedora
dnf install thunderbird

# openSUSE
sudo zypper install thunderbird