Quickstart¶

Conventions ¶

c = ics.Calendar()
e = ics.Event()
a = ics.Attendee()

Importing a Calendar from a URL ¶

Download the calender file through requests or any other library. Error handling is recommended.

from ics import Calendar
import requests

url = "https://urlab.be/events/urlab.ics"
try:
    c = Calendar(requests.get(url).text)
except Exception as e:
    print(e)

print(c)
# <Calendar with 118 events and 0 todo>
print(c.events[2])
# <Event 'TechMardi 20/2015' begin: 2015-12-08 17:30:00+00:00 fixed end: 2015-12-08 22:00:00+00:00 duration: 4:30:00>
e = list(c.timeline)[0]
print("Event '{}' started {}".format(e.summary, e.begin))
# Event 'Workshop Git' started 2015-11-16 17:30:00+00:00

Creating a new Calendar and Add Events ¶

Calendar objects each represent an unique RFC 5545 iCalendar. They contain Event, Todo and Timeline iterators.

Time and date are represented as datetime objects and can be expressed as ISO 8601 strings or with the class constructor.

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)
c
# Calendar(extra=Container('VCALENDAR', []), extra_params={}, version='2.0', prodid='ics.py 0.8.0-dev - http://git.io/lLljaA', scale=None, method=None, events=[Event(extra=Container('VEVENT', []), extra_params={}, timespan=EventTimespan(begin_time=datetime.datetime(2022, 6, 6, 12, 5, 23, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200))), end_time=datetime.datetime(2022, 6, 6, 12, 5, 23, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200))), duration=None, precision='second'), summary='My cool event', uid='e10e6921-5838-4dab-9467-fffcb8091cc3@e10e.org', description='A meaningful description', location=None, url=None, status=None, created=None, last_modified=None, dtstamp=datetime.datetime(2022, 6, 30, 12, 41, 24, 624188, tzinfo=Timezone.from_tzid('UTC')), alarms=[], attach=[], classification=None, transparent=None, organizer=None, geo=None, attendees=[], categories=[])], todos=[])

Get event datetime object details ¶

e.cmp_tuple()
# (datetime.datetime(2022, 6, 6, 12, 5, 23, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200))), datetime.datetime(2022, 6, 6, 13, 5, 23, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200))), 'My cool event')

Converting to all-day event ¶

Transforms event to a rounded-up all-day event.

e.cmp_tuple()
# (datetime.datetime(2022, 6, 6, 12, 5, 23, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200))), datetime.datetime(2022, 6, 6, 13, 5, 23, tzinfo=datetime.timezone(datetime.timedelta(seconds=7200))), 'My cool event')
e.make_all_day()
e.cmp_tuple()
# (datetime.datetime(2022, 6, 6, 0, 0, tzinfo=tzlocal()), datetime.datetime(2022, 6, 7, 0, 0, tzinfo=tzlocal()), 'My cool event')

Exporting a calendar to a file ¶

with open("my.ics", "w") as f:
    f.write(c.serialize())

Managing attendees ¶

Adding attendees

from ics import Attendee

a = Attendee("all@organization.com")
e.add_attendee(a)
e.attendees
# [Attendee(email='all@organization.com', extra={})]

Modifying attendees, find all possible attributes and values in Attendee

e.attendees
# [Attendee(email='all@organization.com', extra={})]
e.attendees[0].common_name = "ALL"
e.attendees
# [Attendee(email='all@organization.com', extra={'CN': ['ALL']})]

Removing attendees

e.attendees
# [Attendee(email='all@organization.com', extra={'CN': ['ALL']})]
del e.attendees[0]
e.attendees
# []