ics: iCalendar (RFC 5545) Parser

0.7.2 · active · verified Wed Apr 15

ics is a Python library for parsing, creating, and manipulating iCalendar files (RFC 5545). It provides an object-oriented API to work with Calendars, Events, Todos, Alarms, and other iCalendar components. The current version is 0.7.2, and releases occur periodically for bug fixes, minor enhancements, and major version upgrades that introduce breaking changes.

Warnings

breaking Python 2 support was completely dropped in version 0.5. The library now only supports Python 3.5 and above.
Fix: Upgrade to Python 3.5+ if you are on an older Python 2.x environment.
breaking Version 0.6 dropped support for Python 3.5 and introduced `TatSu` as a new dependency for parsing. Additionally, the previously private `._unused` attribute was renamed to the public `.extra`.
Fix: Ensure your environment is Python 3.6+ and install `ics` which will pull `TatSu`. Update code from `._unused` to `.extra`.
breaking In version 0.7, `Attendee` and `Organizer` attributes can no longer be set directly to a string. They must be instances of their respective classes.
Fix: Instead of `e.organizer = 'mailto:test@example.com'`, use `from ics import Organizer; e.organizer = Organizer(email='test@example.com')`.
deprecated The `Calendar.str()` method and `Calendar.iter()` will undergo breaking changes in version 0.8. Warnings are emitted in 0.7.1 and later.
Fix: Review the upcoming 0.8 release notes for changes to these methods. Consider preparing for potential adaptation of how calendars are serialized or iterated.
gotcha Version 0.7.1 introduced a dependency on `attrs`. Version 0.7.2 further specified a lower bound of `attrs>=19.1.0`. Users upgrading from older `ics` versions might encounter issues if their `attrs` dependency is too old.
Fix: Ensure `attrs` is up-to-date in your environment, ideally `pip install 'attrs>=19.1.0'` before installing `ics` or allow `pip install ics` to handle the dependency update.

Install

pip install ics Install latest version

Imports

Calendar
```
from ics import Calendar
```
Event
```
from ics import Event
```
Alarm
```
from ics import Alarm
```
Attendee
```
from ics import Attendee
```
Organizer
```
from ics import Organizer
```

Quickstart

This quickstart demonstrates how to create a new iCalendar object, add events with basic properties like name, start time, and duration, and then output the calendar as an iCalendar string. You can also save it to a .ics file.

from ics import Calendar, Event
from datetime import datetime

# Create a new Calendar
c = Calendar()

# Create a new Event
e = Event()
e.name = "My cool event"
e.begin = datetime(2024, 1, 1, 10, 0, 0)
e.duration = {'hours': 1}
e.description = "This is a description for my event."

# Add the event to the calendar
c.events.add(e)

# Add another event
e2 = Event(name="Another event", begin='2024-01-02 14:30:00')
c.events.add(e2)

# Print the iCalendar string
print(str(c))

# To save to a file (example):
# with open('my_calendar.ics', 'w') as f:
#     f.writelines(c)

view raw JSON →