icalendar/docs/usage.rst

iCalendar package
=================

This package 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
-------------

This package is compatible with the following standards:

- :rfc:`5545` - Internet Calendaring and Scheduling Core Object Specification (iCalendar)
- :rfc:`7529` - Non-Gregorian Recurrence Rules in the Internet Calendaring and Scheduling Core Object Specification (iCalendar)
- :rfc:`9074` - "VALARM" Extensions for iCalendar

We do not claim compatibility to the following RFCs. They might work though.

- :rfc:`2445` - obsoleted by :rfc:`5545`
- :rfc:`6868` - Parameter Value Encoding in iCalendar and vCard
- :rfc:`7953` - Calendar Availability
- :rfc:`7986` - New Properties for iCalendar
- :rfc:`9073` - Event Publishing Extensions to iCalendar
- :rfc:`9253` - Support for iCalendar Relationships

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 3 parts: name, parameters, and values. Parameters are optional.

Example 1: a simple content line, with only name and value.

.. code-block:: text

    BEGIN:VCALENDAR

Example 2: a content line with parameters.

.. code-block:: text

    ATTENDEE;CN=Max Rasmussen;ROLE=REQ-PARTICIPANT:MAILTO:example@example.com

The parts in this example are the following.

.. code-block:: text

    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 iCalendar files' structure as having components and subcomponents.

A component will have properties with values. The values
have special types, like integer, text, and datetime. These values are
encoded in a special text format in an iCalendar file. This package contains methods for converting to and from these encodings.

Example 1: this is a VCALENDAR component representing a calendar.

.. code-block:: text

    BEGIN:VCALENDAR
    ... vcalendar properties ...
    END:VCALENDAR

Example 2: The most frequent subcomponent to a VCALENDAR component is a VEVENT. This is a VCALENDAR component with a nested VEVENT subcomponent.

.. code-block:: text

    BEGIN:VCALENDAR
    ... vcalendar properties ...
    BEGIN:VEVENT
    ... vevent properties ...
    END:VEVENT
    END:VCALENDAR


Components
----------

The remaining code snippets in the documentation will use the following important imports.

.. code-block:: pycon

    >>> from icalendar import Calendar, Event

Components are like (Case Insensitive) dicts. So if you want to set a property
you do it like this. The calendar is a component.

.. code-block:: pycon

    >>> cal = Calendar()
    >>> cal['dtstart'] = '20050404T080000'
    >>> cal['summary'] = 'Python meeting about calendaring'
    >>> for k,v in cal.items():
    ...     k,v
    ('DTSTART', '20050404T080000')
    ('SUMMARY', 'Python meeting about calendaring')

NOTE: the recommended way to add components to the calendar is to
create the subcomponent and add it via ``Calendar.add``! The example above adds a
string, but not a ``vText`` component.


You can generate a string for a file with the ``to_ical()`` method.

.. code-block:: pycon

    >>> cal.to_ical()
    b'BEGIN:VCALENDAR\r\nDTSTART:20050404T080000\r\nSUMMARY:Python meeting about calendaring\r\nEND:VCALENDAR\r\n'

The rendered view is easier to read.

.. code-block:: pycon

    BEGIN:VCALENDAR
    DTSTART:20050404T080000
    SUMMARY:Python meeting about calendaring
    END:VCALENDAR

So, let's define a function so we can easily display to_ical() output.

.. code-block:: pycon

    >>> def display(cal):
    ...    return cal.to_ical().decode("utf-8").replace('\r\n', '\n').strip()

You can set multiple properties like this.

.. code-block:: pycon

    >>> cal = Calendar()
    >>> cal['attendee'] = ['MAILTO:maxm@mxm.dk','MAILTO:test@example.com']
    >>> print(display(cal))
    BEGIN:VCALENDAR
    ATTENDEE:MAILTO:maxm@mxm.dk
    ATTENDEE:MAILTO:test@example.com
    END:VCALENDAR

If you don't want to care about whether a property value is a list or
a single value, just use the add() method. It will automatically
convert the property to a list of values if more than one value is
added. Here is an example.

.. code-block:: pycon

    >>> cal = Calendar()
    >>> cal.add('attendee', 'MAILTO:maxm@mxm.dk')
    >>> cal.add('attendee', 'MAILTO:test@example.com')
    >>> print(display(cal))
    BEGIN:VCALENDAR
    ATTENDEE:MAILTO:maxm@mxm.dk
    ATTENDEE:MAILTO:test@example.com
    END:VCALENDAR

Note: this version doesn't check for compliance, so you should look in
the RFC 5545 spec for legal properties for each component, or look in
the icalendar/calendar.py file, where it is at least defined for each
component.


Subcomponents
-------------

Any component can have subcomponents. Eg. inside a calendar there can
be events.  They can be arbitrarily nested. First by making a new
component.

.. code-block:: pycon

    >>> event = Event()
    >>> event['uid'] = '42'
    >>> event['dtstart'] = '20050404T080000'

And then appending it to a "parent".

.. code-block:: pycon

    >>> cal.add_component(event)
    >>> print(display(cal))
    BEGIN:VCALENDAR
    ATTENDEE:MAILTO:maxm@mxm.dk
    ATTENDEE:MAILTO:test@example.com
    BEGIN:VEVENT
    DTSTART:20050404T080000
    UID:42
    END:VEVENT
    END:VCALENDAR

Subcomponents are appended to the subcomponents property on the component.

.. code-block:: pycon

    >>> cal.subcomponents
    [VEVENT({'UID': '42', 'DTSTART': '20050404T080000'})]


Value types
-----------

Property values are utf-8 encoded strings.

This is impractical if you want to use the data for further
computation. The datetime format for example looks like this:
'20050404T080000'. But the package makes it simple to parse and
generate iCalendar formatted strings.

Basically you can make the add() method do the thinking, or you can do it
yourself.

To add a datetime value, you can use Pythons built in datetime types,
and the set the encode parameter to true, and it will convert to the
type defined in the spec.

.. code-block:: pycon

    >>> from datetime import datetime
    >>> cal.add('dtstart', datetime(2005,4,4,8,0,0))
    >>> cal['dtstart'].to_ical()
    b'20050404T080000'

If that doesn't work satisfactorily for some reason, you can also do it
manually.

In 'icalendar.prop', all the iCalendar data types are defined. Each
type has a class that can parse and encode the type.

So if you want to do it manually.

.. code-block:: pycon

    >>> from icalendar import vDatetime
    >>> now = datetime(2005,4,4,8,0,0)
    >>> vDatetime(now).to_ical()
    b'20050404T080000'

So the drill is to initialise the object with a python built in type,
and then call the "to_ical()" method on the object. That will return an
ical encoded string.

You can do it the other way around too. To parse an encoded string, just call
the "from_ical()" method, and it will return an instance of the corresponding
Python type.

.. code-block:: pycon

    >>> vDatetime.from_ical('20050404T080000')
    datetime.datetime(2005, 4, 4, 8, 0)

    >>> vDatetime.from_ical('20050404T080000Z')
    datetime.datetime(2005, 4, 4, 8, 0, tzinfo=ZoneInfo(key='UTC'))

You can also choose to use the decoded() method, which will return a decoded
value directly.

.. code-block:: pycon

    >>> cal = Calendar()
    >>> cal.add('dtstart', datetime(2005,4,4,8,0,0))
    >>> cal['dtstart'].to_ical()
    b'20050404T080000'
    >>> cal.decoded('dtstart')
    datetime.datetime(2005, 4, 4, 8, 0)


Property parameters
-------------------

Property parameters are automatically added, depending on the input value. For
example, for date/time related properties, the value type and timezone
identifier (if applicable) are automatically added here.

.. code-block:: pycon

    >>> import zoneinfo
    >>> event = Event()
    >>> event.add('dtstart', datetime(2010, 10, 10, 10, 0, 0,
    ...                               tzinfo=zoneinfo.ZoneInfo("Europe/Vienna")))

    >>> lines = event.to_ical().splitlines()
    >>> assert (
    ...     b"DTSTART;TZID=Europe/Vienna:20101010T100000"
    ...     in lines)


You can also add arbitrary property parameters by passing a parameters
dictionary to the add method like so.

.. code-block:: pycon

    >>> event = Event()
    >>> event.add('X-TEST-PROP', 'tryout.',
    ...           parameters={'prop1':'val1', 'prop2':'val2'})
    >>> lines = event.to_ical().splitlines()
    >>> assert b"X-TEST-PROP;PROP1=val1;PROP2=val2:tryout." in lines


Example
-------

Here is an example generating a complete iCal calendar file with a
single event that can be loaded into the Mozilla calendar.

Initialize the calendar.

.. code-block:: pycon

    >>> cal = Calendar()
    >>> from datetime import datetime
    >>> import zoneinfo

Some properties are required to be compliant.

.. code-block:: pycon

    >>> cal.add('prodid', '-//My calendar product//mxm.dk//')
    >>> cal.add('version', '2.0')

We need at least one subcomponent for a calendar to be compliant.

.. code-block:: pycon

    >>> event = Event()
    >>> event.add('summary', 'Python meeting about calendaring')
    >>> event.add('dtstart', datetime(2005,4,4,8,0,0,tzinfo=zoneinfo.ZoneInfo("UTC")))
    >>> event.add('dtend', datetime(2005,4,4,10,0,0,tzinfo=zoneinfo.ZoneInfo("UTC")))
    >>> event.add('dtstamp', datetime(2005,4,4,0,10,0,tzinfo=zoneinfo.ZoneInfo("UTC")))

A property with parameters. Notice that they are an attribute on the value.

.. code-block:: pycon

    >>> from icalendar import vCalAddress, vText
    >>> organizer = vCalAddress('MAILTO:noone@example.com')

Automatic encoding is not yet implemented for parameter values, so you
must use the 'v*' types you can import from the icalendar package
(they're defined in ``icalendar.prop``).

.. code-block:: pycon

    >>> organizer.params['cn'] = vText('Max Rasmussen')
    >>> organizer.params['role'] = vText('CHAIR')
    >>> event['organizer'] = organizer
    >>> event['location'] = vText('Odense, Denmark')

    >>> event['uid'] = '20050115T101010/27346262376@mxm.dk'
    >>> event.add('priority', 5)

    >>> attendee = vCalAddress('MAILTO:maxm@example.com')
    >>> attendee.params['cn'] = vText('Max Rasmussen')
    >>> attendee.params['ROLE'] = vText('REQ-PARTICIPANT')
    >>> event.add('attendee', attendee, encode=0)

    >>> attendee = vCalAddress('MAILTO:the-dude@example.com')
    >>> attendee.params['cn'] = vText('The Dude')
    >>> attendee.params['ROLE'] = vText('REQ-PARTICIPANT')
    >>> event.add('attendee', attendee, encode=0)

Add the event to the calendar.

.. code-block:: pycon

    >>> cal.add_component(event)

By extending the event with subcomponents, you can create multiple alarms.

.. code-block:: pycon

    >>> from icalendar import Alarm
    >>> from datetime import timedelta
    >>> alarm_1h_before = Alarm()
    >>> alarm_1h_before.add('action', 'DISPLAY')
    >>> alarm_1h_before.add('trigger', timedelta(hours=-1))
    >>> alarm_1h_before.add('description', 'Reminder: Event in 1 hour')
    >>> event.add_component(alarm_1h_before)

    >>> alarm_24h_before = Alarm()
    >>> alarm_24h_before.add('action', 'DISPLAY')
    >>> alarm_24h_before.add('trigger', timedelta(hours=-24))
    >>> alarm_24h_before.add('description', 'Reminder: Event in 24 hours')
    >>> event.add_component(alarm_24h_before)

Or even recurrence, either from a dictionary or a string.
Note that if you want to add the reccurence rule from a string, you must use the ``vRecur`` property.
Otherwise the rule will be escaped, making it invalid.

.. code-block:: pycon

    >>> event.add('rrule', {'freq': 'daily'})

Write to disk.

.. code-block:: pycon

    >>> import tempfile, os
    >>> directory = tempfile.mkdtemp()
    >>> f = open(os.path.join(directory, 'example.ics'), 'wb')
    >>> f.write(cal.to_ical())
    733
    >>> f.close()

Print out the calendar.

.. code-block:: pycon

    >>> print(cal.to_ical().decode('utf-8')) # doctest: +NORMALIZE_WHITESPACE
    BEGIN:VCALENDAR
    VERSION:2.0
    PRODID:-//My calendar product//mxm.dk//
    BEGIN:VEVENT
    SUMMARY:Python meeting about calendaring
    DTSTART:20050404T080000Z
    DTEND:20050404T100000Z
    DTSTAMP:20050404T001000Z
    UID:20050115T101010/27346262376@mxm.dk
    RRULE:FREQ=DAILY
    ATTENDEE;CN="Max Rasmussen";ROLE=REQ-PARTICIPANT:MAILTO:maxm@example.com
    ATTENDEE;CN="The Dude";ROLE=REQ-PARTICIPANT:MAILTO:the-dude@example.com
    LOCATION:Odense\, Denmark
    ORGANIZER;CN="Max Rasmussen";ROLE=CHAIR:MAILTO:noone@example.com
    PRIORITY:5
    BEGIN:VALARM
    ACTION:DISPLAY
    DESCRIPTION:Reminder: Event in 1 hour
    TRIGGER:-PT1H
    END:VALARM
    BEGIN:VALARM
    ACTION:DISPLAY
    DESCRIPTION:Reminder: Event in 24 hours
    TRIGGER:-P1D
    END:VALARM
    END:VEVENT
    END:VCALENDAR
    <BLANKLINE>

More documentation
==================

Have a look at the `tests <https://github.com/collective/icalendar/tree/main/src/icalendar/tests>`__ of this package to get more examples.
All modules and classes docstrings, which document how they work.