Skip to main content

Python iCalendar implementation (rfc 2445)

Project description

This is an iCalendar rfc 5545 implementation in python. The goal of this project is to offer a calendar library with the relevant and practical features needed for building a calendar application (e.g. recurring events).

ical's main focus is on simplicity, and the internal implementation is based on existing parsing libraries, where possible, making it easy to support as much as possible of rfc5545. It is not a goal to support everything exhaustively, however, the simplicity of the implementation makes it easy to do so.

See documentation for full quickstart and API reference.

Quickstart

The example below creates a Calendar, then adds an all day event to the calendar, then iterates over all events on the calendar.

from datetime import date

from ical.calendar import Calendar
from ical.event import Event

calendar = Calendar()
calendar.events.append(
    Event(summary="Event summary", start=date(2022, 7, 3), end=date(2022, 7, 4)),
)
for event in calendar.timeline:
    print(event.summary)

Reading ics files

This example parses an .ics file from disk and creates a ical.calendar.Calendar object, then prints out the events in order:

from pathlib import Path
from ical.calendar_stream import IcsCalendarStream
from ical.exceptions import CalendarParseError

filename = Path("example/calendar.ics")
with filename.open() as ics_file:
    try:
        calendar = IcsCalendarStream.calendar_from_ics(ics_file.read())
    except CalendarParseError as err:
        print(f"Failed to parse ics file '{str(filename)}': {err}")
    else:
        print([event.summary for event in calendar.timeline])

Writing ics files

This example writes a calendar object to an ics output file:

from pathlib import Path
from ical.calendar_stream import IcsCalendarStream

filename = Path("example/output.ics")
with filename.open() as ics_file:
    ics_file.write(IcsCalendarStream.calendar_to_ics(calendar))

Application-level APIs

The above APIs are used for lower level interaction with calendar components, however applications require a higher level interface to manage some of the underlying complexity. The ical.store library is used to manage state at a higher level (e.g. ensuring timezones are created properly) or handling edits to recurring events.

Recurring events

A calendar event may be recurring (e.g. weekly, monthly, etc). Recurring events are represented in a ical.calendar.Calendar with a single ical.event.Event object, however when observed through a ical.timeline.Timeline will be expanded based on the recurrence rule. See the rrule, rdate, and exdate fields on the ical.event.Event for more details.

Related Work

There are other python rfc5545 implementations that are more mature, and having been around for many years, are still active, and served as reference implementations for this project:

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ical-8.2.0.tar.gz (114.3 kB view details)

Uploaded Source

Built Distribution

ical-8.2.0-py3-none-any.whl (115.3 kB view details)

Uploaded Python 3

File details

Details for the file ical-8.2.0.tar.gz.

File metadata

  • Download URL: ical-8.2.0.tar.gz
  • Upload date:
  • Size: 114.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.6

File hashes

Hashes for ical-8.2.0.tar.gz
Algorithm Hash digest
SHA256 fb65ab62a0dc38fb8fb1a1fce3912ea505873c352b51d5206e3e1253b8416cb8
MD5 85d6d3b2da153da9995186a7f97d527b
BLAKE2b-256 1a811863ef2e43de9aeee7d57eaef1c3f7c0d188ed9f466a0062ce47757952d3

See more details on using hashes here.

File details

Details for the file ical-8.2.0-py3-none-any.whl.

File metadata

  • Download URL: ical-8.2.0-py3-none-any.whl
  • Upload date:
  • Size: 115.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.6

File hashes

Hashes for ical-8.2.0-py3-none-any.whl
Algorithm Hash digest
SHA256 f35d7b80dc88f437dca94d19ae3f7cd99b3cc1118a44779a58481697240aa11d
MD5 d10eede027cc78d229bef5869fac94c5
BLAKE2b-256 21f6f70bf5be07f25fc9b10f25aef772586b3cf1449ce94900c097995a50fcba

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page