Design#
icalendar is used for parsing and generating iCalendar files following the standard in RFC 5545. It should be fully compliant, but it is possible to generate and parse invalid files if you really want to.
Compatibility#
icalendar is compatible with the following RFC standards.
- RFC 2445
obsoleted by RFC 5545
- RFC 5545
Internet Calendaring and Scheduling Core Object Specification (iCalendar)
- RFC 6868
Parameter Value Encoding in iCalendar and vCard
- RFC 7529
Non-Gregorian Recurrence Rules in the Internet Calendaring and Scheduling Core Object Specification (iCalendar)
- RFC 9074
“VALARM” Extensions for iCalendar
- RFC 7953
Calendar Availability
- RFC 7986
New Properties for iCalendar
The maintainers of icalendar do not claim compatibility with the following RFCs. They might work though.
iCalendar file structure#
An iCalendar file is a text file with UTF-8 character encoding in a special format.
It consists of content lines, with each content line defining a property that has three parts: name, parameters, and values. Parameters are optional.
The following examples illustrate the file structure.
The following example iCalendar file consists of a single content line, with only a name and value.
BEGIN:VCALENDAR
The next example iCalendar file consists of a content line with parameters.
ATTENDEE;CN=Max Rasmussen;ROLE=REQ-PARTICIPANT:MAILTO:example@example.com
In the previous iCalendar file example, its parts are the following.
- Name
ATTENDEE- Params
CN=Max Rasmussen;ROLE=REQ-PARTICIPANT- Value
MAILTO:example@example.com
For long content lines, icalendar usually “folds” them to less than 75 characters.
On a higher level, you can think of an iCalendar file’s structure as having components and subcomponents.
A component will have properties with values. The values have special types, including integer, text, and datetime. These values are encoded in a special text format in an iCalendar file. icalendar contains methods for converting to and from these encodings.
The following example is a VCALENDAR component representing a calendar.
BEGIN:VCALENDAR
... vcalendar properties ...
END:VCALENDAR
The most frequent subcomponent to a VCALENDAR component is a VEVENT.
This following example is a VCALENDAR component with a nested VEVENT subcomponent.
BEGIN:VCALENDAR
... vcalendar properties ...
BEGIN:VEVENT
... vevent properties ...
END:VEVENT
END:VCALENDAR