Skip to main content
`Ctrl`+`K`

# API Reference

## icalendar.attr

Attributes of Components and properties.

icalendar.attr.multi_language_text_property(main_prop: str, compatibility_prop: str, doc: str) → property

  This creates a text property.

  This property can be defined several times with different `LANGUAGE` parameters.

  Parameters:

    - main_prop (str) – The property to set and get, such as `NAME`

    - compatibility_prop (str) – An old property used before, such as `X-WR-CALNAME`

    - doc (str) – The documentation string

icalendar.attr.single_int_property(prop: str, default: int, doc: str) → property

  Create a property for an int value that exists only once.

  Parameters:

    - prop – The name of the property

    - default – The default value

    - doc – The documentation string

icalendar.attr.single_utc_property(name: str, docs: str) → property

  Create a property to access a value of datetime in UTC timezone.

  Parameters:

    - name – name of the property

    - docs – documentation string

## icalendar.alarms

Compute the times and states of alarms.

This takes different calendar software into account and the RFC 9074 (Alarm Extension).

- RFC 9074 defines an ACKNOWLEDGED property in the VALARM.

- Outlook does not export VALARM information.

- Google Calendar uses the DTSTAMP to acknowledge the alarms.

- Thunderbird snoozes the alarms with a X-MOZ-SNOOZE-TIME attribute in the event.

- Thunderbird acknowledges the alarms with a X-MOZ-LASTACK attribute in the event.

- Etar deletes alarms that are acknowledged.

- Nextcloud’s Webinterface does not do anything with the alarms when the time passes.

class icalendar.alarms.AlarmTime(alarm: Alarm, trigger: datetime, acknowledged_until: datetime | None = None, snoozed_until: datetime | None = None, parent: Parent | None = None)

  An alarm time with all the information.

  property acknowledged: datetime | None

    The time in UTC at which this alarm was last acknowledged.

    If the alarm was not acknowledged (dismissed), then this is None.

  property alarm: Alarm

    The alarm component.

  is_active() → bool

    Whether this alarm is active (True) or acknowledged (False).

    For example, in some calendar software, this is True until the user looks at the alarm message and clicked the dismiss button.

    Alarms can be in local time (without a timezone). To calculate if the alarm really happened, we need it to be in a timezone. If a timezone is required but not given, we throw an IncompleteAlarmInformation.

  property parent: Event | Todo | None

    This is the component that contains the alarm.

    This is None if you did not use Alarms.set_component().

  property trigger: date

    This is the time to trigger the alarm.

    If the alarm has been snoozed, this can differ from the TRIGGER property.

class icalendar.alarms.Alarms(component: Alarm | Event | Todo | None = None)

  Compute the times and states of alarms.

  This is an example using RFC 9074. One alarm is 30 minutes before the event and acknowledged. Another alarm is 15 minutes before the event and still active.

      >>> from icalendar import Event, Alarms
      >>> event = Event.from_ical(
      ... '''BEGIN:VEVENT
      ... CREATED:20210301T151004Z
      ... UID:AC67C078-CED3-4BF5-9726-832C3749F627
      ... DTSTAMP:20210301T151004Z
      ... DTSTART;TZID=America/New_York:20210302T103000
      ... DTEND;TZID=America/New_York:20210302T113000
      ... SUMMARY:Meeting
      ... BEGIN:VALARM
      ... UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
      ... TRIGGER:-PT30M
      ... ACKNOWLEDGED:20210302T150004Z
      ... DESCRIPTION:Event reminder
      ... ACTION:DISPLAY
      ... END:VALARM
      ... BEGIN:VALARM
      ... UID:8297C37D-BA2D-4476-91AE-C1EAA364F8E1
      ... TRIGGER:-PT15M
      ... DESCRIPTION:Event reminder
      ... ACTION:DISPLAY
      ... END:VALARM
      ... END:VEVENT
      ... ''')
      >>> alarms = Alarms(event)
      >>> len(alarms.times)   # all alarms including those acknowledged
      2
      >>> len(alarms.active)  # the alarms that are not acknowledged, yet
      1
      >>> alarms.active[0].trigger  # this alarm triggers 15 minutes before 10:30
      datetime.datetime(2021, 3, 2, 10, 15, tzinfo=ZoneInfo(key='America/New_York'))

  RFC 9074 specifies that alarms can also be triggered by proximity. This is not implemented yet.

  acknowledge_until(dt: date | None) → None

    This is the time in UTC when all the alarms of this component were acknowledged.

    Only the last call counts.

    Since RFC 9074 (Alarm Extension) was created later, calendar implementations differ in how they acknowledge alarms. For example, Thunderbird and Google Calendar store the last time an event has been acknowledged because of an alarm. All alarms that happen before this time count as acknowledged.

  property active: list[AlarmTime]

    The alarm times that are still active and not acknowledged.

    This considers snoozed alarms.

    Alarms can be in local time (without a timezone). To calculate if the alarm really happened, we need it to be in a timezone. If a timezone is required but not given, we throw an IncompleteAlarmInformation.

  add_alarm(alarm: Alarm) → None

    Optional: Add an alarm component.

  add_component(component: Alarm | Event | Todo)

    Add a component.

    If this is an alarm, it is added. Events and Todos are added as a parent and all their alarms are added, too.

  set_end(dt: date | None)

    Set the end of the component.

    If you have only absolute alarms, this is not required. If you have alarms relative to the end of a compoment, set the end here.

  set_local_timezone(tzinfo: tzinfo | str | None)

    Set the local timezone.

    Events are sometimes in local time. In order to compute the exact time of the alarm, some alarms without timezone are considered local.

    Some computations work without setting this, others don’t. If they need this information, expect a LocalTimezoneMissing exception somewhere down the line.

  set_parent(parent: Event | Todo)

    Set the parent of all the alarms.

    If you would like to collect alarms from a component, use add_component

  set_start(dt: date | None)

    Set the start of the component.

    If you have only absolute alarms, this is not required. If you have alarms relative to the start of a compoment, set the start here.

  snooze_until(dt: date | None) → None

    This is the time in UTC when all the alarms of this component were snoozed.

    Only the last call counts.

    The alarms are supposed to turn up again at dt when they are not acknowledged but snoozed.

  property times: list[AlarmTime]

    Compute and return the times of the alarms given.

    If the information for calculation is incomplete, this will raise a IncompleteAlarmInformation exception.

    Please make sure to set all the required parameters before calculating. If you forget to set the acknowledged times, that is not problem.

exception icalendar.alarms.ComponentEndMissing

  We are missing the end of a component that the alarm is for.

  Use Alarms.set_end().

exception icalendar.alarms.ComponentStartMissing

  We are missing the start of a component that the alarm is for.

  Use Alarms.set_start().

exception icalendar.alarms.IncompleteAlarmInformation

  The alarms cannot be calculated yet because information is missing.

## icalendar.cal

Calendar is a dictionary like Python object that can render itself as VCAL files according to RFC 5545.

These are the defined components.

class icalendar.cal.Alarm(*args, **kwargs)

  A “VALARM” calendar component is a grouping of component properties that defines an alarm or reminder for an event or a to-do. For example, it may be used to define a reminder for a pending event or an overdue to-do.

  property ACKNOWLEDGED: datetime | None

    The ACKNOWLEDGED property. datetime in UTC

    All values will be converted to a datetime in UTC. This is defined in RFC 9074:

    Purpose: This property specifies the UTC date and time at which the corresponding alarm was last sent or acknowledged.

    This property is used to specify when an alarm was last sent or acknowledged. This allows clients to determine when a pending alarm has been acknowledged by a calendar user so that any alerts can be dismissed across multiple devices. It also allows clients to track repeating alarms or alarms on recurring events or to-dos to ensure that the right number of missed alarms can be tracked.

    Clients SHOULD set this property to the current date-time value in UTC when a calendar user acknowledges a pending alarm. Certain kinds of alarms, such as email-based alerts, might not provide feedback as to when the calendar user sees them. For those kinds of alarms, the client SHOULD set this property when the alarm is triggered and the action is successfully carried out.

    When an alarm is triggered on a client, clients can check to see if an “ACKNOWLEDGED” property is present. If it is, and the value of that property is greater than or equal to the computed trigger time for the alarm, then the client SHOULD NOT trigger the alarm. Similarly, if an alarm has been triggered and an “alert” has been presented to a calendar user, clients can monitor the iCalendar data to determine whether an “ACKNOWLEDGED” property is added or changed in the alarm component. If the value of any “ACKNOWLEDGED” property in the alarm changes and is greater than or equal to the trigger time of the alarm, then clients SHOULD dismiss or cancel any “alert” presented to the calendar user.

  property DURATION: timedelta | None

    The DURATION property of an alarm component.

    The alarm can be defined such that it triggers repeatedly. A definition of an alarm with a repeating trigger MUST include both the “DURATION” and “REPEAT” properties. The “DURATION” property specifies the delay period, after which the alarm will repeat.

  property REPEAT: int

    The REPEAT property of an alarm component.

    The alarm can be defined such that it triggers repeatedly. A definition of an alarm with a repeating trigger MUST include both the “DURATION” and “REPEAT” properties. The “DURATION” property specifies the delay period, after which the alarm will repeat. The “REPEAT” property specifies the number of additional repetitions that the alarm will be triggered. This repetition count is in addition to the initial triggering of the alarm.

  property TRIGGER: timedelta | datetime | None

    The TRIGGER property.

    Purpose: This property specifies when an alarm will trigger.

    Value Type: The default value type is DURATION. The value type can be set to a DATE-TIME value type, in which case the value MUST specify a UTC-formatted DATE-TIME value.

    Either a positive or negative duration may be specified for the “TRIGGER” property. An alarm with a positive duration is triggered after the associated start or end of the event or to-do. An alarm with a negative duration is triggered before the associated start or end of the event or to-do.

    Accepted values: datetime, timedelta. If the attribute has invalid values, we raise InvalidCalendar. If the value is absent, we return None. You can also delete the value with del or by setting it to None.

  property TRIGGER_RELATED: str

    The RELATED parameter of the TRIGGER property.

    Values are either “START” (default) or “END”.

    A value of START will set the alarm to trigger off the start of the associated event or to-do. A value of END will set the alarm to trigger off the end of the associated event or to-do.

    In this example, we create an alarm that triggers two hours after the end of its parent component:

        >>> from icalendar import Alarm
        >>> from datetime import timedelta
        >>> alarm = Alarm()
        >>> alarm.TRIGGER = timedelta(hours=2)
        >>> alarm.TRIGGER_RELATED = "END"

  class Triggers(start: tuple[timedelta], end: tuple[timedelta], absolute: tuple[datetime])

    The computed times of alarm triggers.

    start - triggers relative to the start of the Event or Todo (timedelta)

    end - triggers relative to the end of the Event or Todo (timedelta)

    absolute - triggers at a datetime in UTC

    absolute: tuple[datetime]

      Alias for field number 2

    end: tuple[timedelta]

      Alias for field number 1

    start: tuple[timedelta]

      Alias for field number 0

  property triggers

    The computed triggers of an Alarm.

    This takes the TRIGGER, DURATION and REPEAT properties into account.

    Here, we create an alarm that triggers 3 times before the start of the parent component:

        >>> from icalendar import Alarm
        >>> from datetime import timedelta
        >>> alarm = Alarm()
        >>> alarm.TRIGGER = timedelta(hours=-4)  # trigger 4 hours before START
        >>> alarm.DURATION = timedelta(hours=1)  # after 1 hour trigger again
        >>> alarm.REPEAT = 2  # trigger 2 more times
        >>> alarm.triggers.start == (timedelta(hours=-4),  timedelta(hours=-3),  timedelta(hours=-2))
        True
        >>> alarm.triggers.end
        ()
        >>> alarm.triggers.absolute
        ()

  property uid: str

    UID specifies the persistent, globally unique identifier for a component.

    We recommend using `uuid.uuid4()` to generate new values.

    Returns:

      The value of the UID property as a string or `""` if no value is set.

    Description:

      The “UID” itself MUST be a globally unique identifier. The generator of the identifier MUST guarantee that the identifier is unique.

      This is the method for correlating scheduling messages with the referenced “VEVENT”, “VTODO”, or “VJOURNAL” calendar component. The full range of calendar components specified by a recurrence set is referenced by referring to just the “UID” property value corresponding to the calendar component. The “RECURRENCE-ID” property allows the reference to an individual instance within the recurrence set.

      This property is an important method for group-scheduling applications to match requests with later replies, modifications, or deletion requests. Calendaring and scheduling applications MUST generate this property in “VEVENT”, “VTODO”, and “VJOURNAL” calendar components to assure interoperability with other group- scheduling applications. This identifier is created by the calendar system that generates an iCalendar object.

      Implementations MUST be able to receive and persist values of at least 255 octets for this property, but they MUST NOT truncate values in the middle of a UTF-8 multi-octet sequence.

      RFC 7986 states that UID can be used, for example, to identify duplicate calendar streams that a client may have been given access to. It can be used in conjunction with the “LAST-MODIFIED” property also specified on the “VCALENDAR” object to identify the most recent version of a calendar.

    Conformance:

      RFC 5545 states that the “UID” property can be specified on “VEVENT”, “VTODO”, and “VJOURNAL” calendar components. RFC 7986 modifies the definition of the “UID” property to allow it to be defined in an iCalendar object. RFC 9074 adds a “UID” property to “VALARM” components to allow a unique identifier to be specified. The value of this property can then be used to refer uniquely to the “VALARM” component.

      This property can be specified once only.

    Security:

      RFC 7986 states that UID values MUST NOT include any data that might identify a user, host, domain, or any other security- or privacy-sensitive information. It is RECOMMENDED that calendar user agents now generate “UID” values that are hex-encoded random Universally Unique Identifier (UUID) values as defined in Sections 4.4 and 4.5 of RFC 4122. You can use the `uuid` module to generate new UUIDs.

    Compatibility:

      For Alarms, `X-ALARMUID` is also considered.

    Examples

    The following is an example of such a property value: `5FC53010-1267-4F8E-BC28-1D7AE55A7C99`.

    Set the UID of a calendar:

        >>> from icalendar import Calendar
        >>> from uuid import uuid4
        >>> calendar = Calendar()
        >>> calendar.uid = uuid4()
        >>> print(calendar.to_ical())
        BEGIN:VCALENDAR
        UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
        END:VCALENDAR

class icalendar.cal.Calendar(*args, **kwargs)

  The “VCALENDAR” object is a collection of calendar information. This information can include a variety of components, such as “VEVENT”, “VTODO”, “VJOURNAL”, “VFREEBUSY”, “VTIMEZONE”, or any other type of calendar component.

  add_missing_timezones(first_date: date = datetime.date(1970, 1, 1), last_date: date = datetime.date(2038, 1, 1))

    Add all missing VTIMEZONE components.

    This adds all the timezone components that are required.

    Note

    Timezones that are not known will not be added.

    Parameters:

      - first_date – earlier than anything that happens in the calendar

      - last_date – later than anything happening in the calendar

        >>> from icalendar import Calendar, Event
        >>> from datetime import datetime
        >>> from zoneinfo import ZoneInfo
        >>> calendar = Calendar()
        >>> event = Event()
        >>> calendar.add_component(event)
        >>> event.start = datetime(1990, 10, 11, 12, tzinfo=ZoneInfo("Europe/Berlin"))
        >>> calendar.timezones
        []
        >>> calendar.add_missing_timezones()
        >>> calendar.timezones[0].tz_name
        'Europe/Berlin'
        >>> calendar.get_missing_tzids()  # check that all are added
        set()

  property calendar_name: str | None

    This property specifies the name of the calendar.

    This implements RFC 7986 `NAME` and `X-WR-CALNAME`.

    Property Parameters:

      IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.

    Conformance:

      This property can be specified multiple times in an iCalendar object. However, each property MUST represent the name of the calendar in a different language.

    Description:

      This property is used to specify a name of the iCalendar object that can be used by calendar user agents when presenting the calendar data to a user. Whilst a calendar only has a single name, multiple language variants can be specified by including this property multiple times with different “LANGUAGE” parameter values on each.

    Example

    Below, we set the name of the calendar.

        >>> from icalendar import Calendar
        >>> calendar = Calendar()
        >>> calendar.calendar_name = "My Calendar"
        >>> print(calendar.to_ical())
        BEGIN:VCALENDAR
        NAME:My Calendar
        END:VCALENDAR

  property categories: list[str]

    This property defines the categories for a component.

    Property Parameters:

      IANA, non-standard, and language property parameters can be specified on this property.

    Conformance:

      The property can be specified within “VEVENT”, “VTODO”, or “VJOURNAL” calendar components. Since RFC 7986 it can also be defined on a “VCALENDAR” component.

    Description:

      This property is used to specify categories or subtypes of the calendar component. The categories are useful in searching for a calendar component of a particular type and category. Within the “VEVENT”, “VTODO”, or “VJOURNAL” calendar components, more than one category can be specified as a COMMA-separated list of categories.

    Example

    Below, we add the categories to an event:

        >>> from icalendar import Event
        >>> event = Event()
        >>> event.categories = ["Work", "Meeting"]
        >>> print(event.to_ical())
        BEGIN:VEVENT
        CATEGORIES:Work,Meeting
        END:VEVENT
        >>> event.categories.append("Lecture")
        >>> event.categories == ["Work", "Meeting", "Lecture"]
        True

    Note

    At present, we do not take the LANGUAGE parameter into account.

  property color: str

    This property specifies a color used for displaying the calendar.

    This implements RFC 7986 `COLOR` and `X-APPLE-CALENDAR-COLOR`. Please note that since RFC 7986, subcomponents can have their own color.

    Property Parameters:

      IANA and non-standard property parameters can be specified on this property.

    Conformance:

      This property can be specified once in an iCalendar object or in `VEVENT`, `VTODO`, or `VJOURNAL` calendar components.

    Description:

      This property specifies a color that clients MAY use when presenting the relevant data to a user. Typically, this would appear as the “background” color of events or tasks. The value is a case-insensitive color name taken from the CSS3 set of names, defined in Section 4.3 of W3C.REC-css3-color-20110607.

    Example

    `"turquoise"`, `"#ffffff"`

        >>> from icalendar import Calendar
        >>> calendar = Calendar()
        >>> calendar.color = "black"
        >>> print(calendar.to_ical())
        BEGIN:VCALENDAR
        COLOR:black
        END:VCALENDAR

  property description: str | None

    This property specifies the description of the calendar.

    This implements RFC 7986 `DESCRIPTION` and `X-WR-CALDESC`.

    Conformance:

      This property can be specified multiple times in an iCalendar object. However, each property MUST represent the description of the calendar in a different language.

    Description:

      This property is used to specify a lengthy textual description of the iCalendar object that can be used by calendar user agents when describing the nature of the calendar data to a user. Whilst a calendar only has a single description, multiple language variants can be specified by including this property multiple times with different “LANGUAGE” parameter values on each.

    Example

    Below, we add a description to a calendar.

        >>> from icalendar import Calendar
        >>> calendar = Calendar()
        >>> calendar.description = "This is a calendar"
        >>> print(calendar.to_ical())
        BEGIN:VCALENDAR
        DESCRIPTION:This is a calendar
        END:VCALENDAR

  property events: list[Event]

    All event components in the calendar.

    This is a shortcut to get all events. Modifications do not change the calendar. Use `Component.add_component()`.

        >>> from icalendar import Calendar
        >>> calendar = Calendar.example()
        >>> event = calendar.events[0]
        >>> event.start
        datetime.date(2022, 1, 1)
        >>> print(event["SUMMARY"])
        New Year's Day

  classmethod example(name: str = 'example') → Calendar

    Return the calendar example with the given name.

  property freebusy: list[FreeBusy]

    All FreeBusy components in the calendar.

    This is a shortcut to get all FreeBusy. Modifications do not change the calendar. Use `Component.add_component()`.

  classmethod from_ical(st, multiple=False)

    Populates the component recursively from a string.

  get_missing_tzids() → set[str]

    The set of missing timezone component tzids.

    To create a RFC 5545 compatible calendar, all of these timezones should be added.

  get_used_tzids() → set[str]

    The set of TZIDs in use.

    This goes through the whole calendar to find all occurrences of timezone information like the TZID parameter in all attributes.

        >>> from icalendar import Calendar
        >>> calendar = Calendar.example("timezone_rdate")
        >>> calendar.get_used_tzids()
        {'posix/Europe/Vaduz'}

    Even if you use UTC, this will not show up.

  property timezones: list[Timezone]

    Return the timezones components in this calendar.

        >>> from icalendar import Calendar
        >>> calendar = Calendar.example("pacific_fiji")
        >>> [timezone.tz_name for timezone in calendar.timezones]
        ['custom_Pacific/Fiji']

    Note

    This is a read-only property.

  property todos: list[Todo]

    All todo components in the calendar.

    This is a shortcut to get all todos. Modifications do not change the calendar. Use `Component.add_component()`.

  property uid: str

    UID specifies the persistent, globally unique identifier for a component.

    We recommend using `uuid.uuid4()` to generate new values.

    Returns:

      The value of the UID property as a string or `""` if no value is set.

    Description:

      The “UID” itself MUST be a globally unique identifier. The generator of the identifier MUST guarantee that the identifier is unique.

      This is the method for correlating scheduling messages with the referenced “VEVENT”, “VTODO”, or “VJOURNAL” calendar component. The full range of calendar components specified by a recurrence set is referenced by referring to just the “UID” property value corresponding to the calendar component. The “RECURRENCE-ID” property allows the reference to an individual instance within the recurrence set.

      This property is an important method for group-scheduling applications to match requests with later replies, modifications, or deletion requests. Calendaring and scheduling applications MUST generate this property in “VEVENT”, “VTODO”, and “VJOURNAL” calendar components to assure interoperability with other group- scheduling applications. This identifier is created by the calendar system that generates an iCalendar object.

      Implementations MUST be able to receive and persist values of at least 255 octets for this property, but they MUST NOT truncate values in the middle of a UTF-8 multi-octet sequence.

      RFC 7986 states that UID can be used, for example, to identify duplicate calendar streams that a client may have been given access to. It can be used in conjunction with the “LAST-MODIFIED” property also specified on the “VCALENDAR” object to identify the most recent version of a calendar.

    Conformance:

      RFC 5545 states that the “UID” property can be specified on “VEVENT”, “VTODO”, and “VJOURNAL” calendar components. RFC 7986 modifies the definition of the “UID” property to allow it to be defined in an iCalendar object. RFC 9074 adds a “UID” property to “VALARM” components to allow a unique identifier to be specified. The value of this property can then be used to refer uniquely to the “VALARM” component.

      This property can be specified once only.

    Security:

      RFC 7986 states that UID values MUST NOT include any data that might identify a user, host, domain, or any other security- or privacy-sensitive information. It is RECOMMENDED that calendar user agents now generate “UID” values that are hex-encoded random Universally Unique Identifier (UUID) values as defined in Sections 4.4 and 4.5 of RFC 4122. You can use the `uuid` module to generate new UUIDs.

    Compatibility:

      For Alarms, `X-ALARMUID` is also considered.

    Examples

    The following is an example of such a property value: `5FC53010-1267-4F8E-BC28-1D7AE55A7C99`.

    Set the UID of a calendar:

        >>> from icalendar import Calendar
        >>> from uuid import uuid4
        >>> calendar = Calendar()
        >>> calendar.uid = uuid4()
        >>> print(calendar.to_ical())
        BEGIN:VCALENDAR
        UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
        END:VCALENDAR

class icalendar.cal.Component(*args, **kwargs)

  Component is the base object for calendar, Event and the other components defined in RFC 5545. Normally you will not use this class directly, but rather one of the subclasses.

  property DTSTAMP: datetime | None

    The DTSTAMP property. datetime in UTC

    All values will be converted to a datetime in UTC. RFC 5545:

    > Conformance: This property MUST be included in the “VEVENT”, “VTODO”, “VJOURNAL”, or “VFREEBUSY” calendar components.

    > Description: In the case of an iCalendar object that specifies a “METHOD” property, this property specifies the date and time that the instance of the iCalendar object was created. In the case of an iCalendar object that doesn’t specify a “METHOD” property, this property specifies the date and time that the information associated with the calendar component was last revised in the calendar store.

    > The value MUST be specified in the UTC time format.

    > In the case of an iCalendar object that doesn’t specify a “METHOD” property, this property is equivalent to the “LAST-MODIFIED” property.

  property LAST_MODIFIED: datetime | None

    The LAST-MODIFIED property. datetime in UTC

    All values will be converted to a datetime in UTC. RFC 5545:

    > Purpose: This property specifies the date and time that the information associated with the calendar component was last revised in the calendar store.

    > Note: This is analogous to the modification date and time for a file in the file system.

    > Conformance: This property can be specified in the “VEVENT”, “VTODO”, “VJOURNAL”, or “VTIMEZONE” calendar components.

  add(name, value, parameters=None, encode=1)

    Add a property.

    Parameters:

      - name (string) – Name of the property.

      - value (Python native type or icalendar property type.) – Value of the property. Either of a basic Python type of any of the icalendar’s own property types.

      - parameters (Dictionary) – Property parameter dictionary for the value. Only available, if encode is set to True.

      - encode (Boolean) – True, if the value should be encoded to one of icalendar’s own property types (Fallback is “vText”) or False, if not.

    Returns:

      None

  add_component(component: Component)

    Add a subcomponent to this component.

  content_line(name, value, sorted=True)

    Returns property as content line.

  content_lines(sorted=True)

    Converts the Component and subcomponents into content lines.

  decoded(name, default=[])

    Returns decoded value of property.

  classmethod from_ical(st, multiple=False)

    Populates the component recursively from a string.

  get_inline(name, decode=1)

    Returns a list of values (split on comma).

  is_empty()

    Returns True if Component has no items or subcomponents, else False.

  is_thunderbird() → bool

    Whether this component has attributes that indicate that Mozilla Thunderbird created it.

  property_items(recursive=True, sorted=True) → list[tuple[str, object]]

    Returns properties in this component and subcomponents as: [(name, value), …]

  set_inline(name, values, encode=1)

    Converts a list of values into comma separated string and sets value to that.

  to_ical(sorted=True)
    Parameters:

      sorted – Whether parameters and properties should be lexicographically sorted.

  walk(name=None, select=<function Component.<lambda>>) → list[Component]

    Recursively traverses component and subcomponents. Returns sequence of same. If name is passed, only components with name will be returned.

    Parameters:

      - name – The name of the component or None such as `VEVENT`.

      - select – A function that takes the component as first argument and returns True/False.

    Returns:

      A list of components that match.

    Return type:

      list[Component]

class icalendar.cal.ComponentFactory(*args, **kwargs)

  All components defined in RFC 5545 are registered in this factory class. To get a component you can use it like this.

class icalendar.cal.Event(*args, **kwargs)

  A “VEVENT” calendar component is a grouping of component properties that represents a scheduled amount of time on a calendar. For example, it can be an activity, such as a one-hour long department meeting from 8:00 AM to 9:00 AM, tomorrow.

  property DTEND: date | None

    The DTEND property.

    The “DTEND” property for a “VEVENT” calendar component specifies the non-inclusive end of the event.

    Accepted values: datetime, date. If the attribute has invalid values, we raise InvalidCalendar. If the value is absent, we return None. You can also delete the value with del or by setting it to None.

  property DTSTART: date | None

    The DTSTART property.

    The “DTSTART” property for a “VEVENT” specifies the inclusive start of the event.

    Accepted values: datetime, date. If the attribute has invalid values, we raise InvalidCalendar. If the value is absent, we return None. You can also delete the value with del or by setting it to None.

  property DURATION: timedelta | None

    The DURATION property.

    The “DTSTART” property for a “VEVENT” specifies the inclusive start of the event. The “DURATION” property in conjunction with the DTSTART property for a “VEVENT” calendar component specifies the non-inclusive end of the event.

    If you would like to calculate the duration of a VEVENT, do not use this. Instead use the duration property (lower case).

  property X_MOZ_LASTACK: datetime | None

    The X-MOZ-LASTACK property. datetime in UTC

    All values will be converted to a datetime in UTC. Thunderbird: Alarms before this time are acknowledged.

  property X_MOZ_SNOOZE_TIME: datetime | None

    The X-MOZ-SNOOZE-TIME property. datetime in UTC

    All values will be converted to a datetime in UTC. Thunderbird: Alarms before this time are snoozed.

  property alarms: Alarms

    Compute the alarm times for this component.

        >>> from icalendar import Event
        >>> event = Event.example("rfc_9074_example_1")
        >>> len(event.alarms.times)
        1
        >>> alarm_time = event.alarms.times[0]
        >>> alarm_time.trigger  # The time when the alarm pops up
        datetime.datetime(2021, 3, 2, 10, 15, tzinfo=ZoneInfo(key='America/New_York'))
        >>> alarm_time.is_active()  # This alarm has not been acknowledged
        True

    Note that this only uses DTSTART and DTEND, but ignores RDATE, EXDATE, and RRULE properties.

  property categories: list[str]

    This property defines the categories for a component.

    Property Parameters:

      IANA, non-standard, and language property parameters can be specified on this property.

    Conformance:

      The property can be specified within “VEVENT”, “VTODO”, or “VJOURNAL” calendar components. Since RFC 7986 it can also be defined on a “VCALENDAR” component.

    Description:

      This property is used to specify categories or subtypes of the calendar component. The categories are useful in searching for a calendar component of a particular type and category. Within the “VEVENT”, “VTODO”, or “VJOURNAL” calendar components, more than one category can be specified as a COMMA-separated list of categories.

    Example

    Below, we add the categories to an event:

        >>> from icalendar import Event
        >>> event = Event()
        >>> event.categories = ["Work", "Meeting"]
        >>> print(event.to_ical())
        BEGIN:VEVENT
        CATEGORIES:Work,Meeting
        END:VEVENT
        >>> event.categories.append("Lecture")
        >>> event.categories == ["Work", "Meeting", "Lecture"]
        True

    Note

    At present, we do not take the LANGUAGE parameter into account.

  property color: str

    This property specifies a color used for displaying the component.

    This implements RFC 7986 `COLOR` property.

    Property Parameters:

      IANA and non-standard property parameters can be specified on this property.

    Conformance:

      This property can be specified once in an iCalendar object or in `VEVENT`, `VTODO`, or `VJOURNAL` calendar components.

    Description:

      This property specifies a color that clients MAY use when presenting the relevant data to a user. Typically, this would appear as the “background” color of events or tasks. The value is a case-insensitive color name taken from the CSS3 set of names, defined in Section 4.3 of W3C.REC-css3-color-20110607.

    Example

    `"turquoise"`, `"#ffffff"`

        >>> from icalendar import Todo
        >>> todo = Todo()
        >>> todo.color = "green"
        >>> print(todo.to_ical())
        BEGIN:VTODO
        COLOR:green
        END:VTODO

  property duration: timedelta

    The duration of the VEVENT.

    This duration is calculated from the start and end of the event. You cannot set the duration as it is unclear what happens to start and end.

  property end: date | datetime

    The end of the component.

    Invalid values raise an InvalidCalendar error. If there is no end, we also raise an IncompleteComponent error.

  classmethod example(name: str = 'rfc_9074_example_3') → Event

    Return the calendar example with the given name.

  property exdates: list[date | datetime]

    EXDATE defines the list of DATE-TIME exceptions for recurring components.

    EXDATE is defined in RFC 5545.

    Value Type:

      The default value type for this property is DATE-TIME. The value type can be set to DATE.

    Property Parameters:

      IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

    Conformance:

      This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

    Description:

      The exception dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). When duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

      The “EXDATE” property can be used to exclude the value specified in “DTSTART”. However, in such cases, the original “DTSTART” date MUST still be maintained by the calendaring and scheduling system because the original “DTSTART” value has inherent usage dependencies by other properties such as the “RECURRENCE-ID”.

    Example

    Below, we add an exdate in a list and get the resulting list of exdates.

        >>> from icalendar import Event
        >>> from datetime import datetime
        >>> event = Event()

        # Add a list of excluded dates
        >>> event.add("EXDATE", [datetime(2025, 4, 28, 16, 5)])
        >>> event.exdates
        [datetime.datetime(2025, 4, 28, 16, 5)]

    Note

    You cannot modify the EXDATE value by modifying the result. Use `icalendar.cal.Component.add()` to add values.

    If you want to compute recurrences, have a look at Related projects.

  property rdates: list[tuple[date, None] | tuple[datetime, None] | tuple[datetime, datetime]]

    The RDATE property defines the list of DATE-TIME values for recurring components.

    RDATE is defined in RFC 5545. The return value is a list of tuples `(start, end)`.

    `start` can be a `datetime.date` or a `datetime.datetime`, with and without timezone.

    `end` is `None` if the end is not specified and a `datetime.datetime` if the end is specified.

    Value Type:

      The default value type for this property is DATE-TIME. The value type can be set to DATE or PERIOD.

    Property Parameters:

      IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

    Conformance:

      This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

    Description:

      This property can appear along with the “RRULE” property to define an aggregate set of repeating occurrences. When they both appear in a recurring component, the recurrence instances are defined by the union of occurrences defined by both the “RDATE” and “RRULE”.

      The recurrence dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

    Example

    Below, we set one RDATE in a list and get the resulting tuple of start and end.

        >>> from icalendar import Event
        >>> from datetime import datetime
        >>> event = Event()

        # Add a list of recurrence dates
        >>> event.add("RDATE", [datetime(2025, 4, 28, 16, 5)])
        >>> event.rdates
        [(datetime.datetime(2025, 4, 28, 16, 5), None)]

    Note

    You cannot modify the RDATE value by modifying the result. Use `icalendar.cal.Component.add()` to add values.

    If you want to compute recurrences, have a look at Related projects.

  property rrules: list[vRecur]

    RRULE defines a rule or repeating pattern for recurring components.

    RRULE is defined in RFC 5545. RFC 7529 adds the `SKIP` parameter `icalendar.prop.vSkip`.

    Property Parameters:

      IANA and non-standard property parameters can be specified on this property.

    Conformance:

      This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component, but it SHOULD NOT be specified more than once. The recurrence set generated with multiple “RRULE” properties is undefined.

    Description:

      The recurrence rule, if specified, is used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD be synchronized with the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value not synchronized with the recurrence rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE- TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

      The “DTSTART” property specified within the iCalendar object defines the first instance of the recurrence. In most cases, a “DTSTART” property of DATE-TIME value type used with a recurrence rule, should be specified as a date with local time and time zone reference to make sure all the recurrence instances start at the same local time regardless of time zone changes.

      If the duration of the recurring component is specified with the “DTEND” or “DUE” property, then the same exact duration will apply to all the members of the generated recurrence set. Else, if the duration of the recurring component is specified with the “DURATION” property, then the same nominal duration will apply to all the members of the generated recurrence set and the exact duration of each recurrence instance will depend on its specific start time. For example, recurrence instances of a nominal duration of one day will have an exact duration of more or less than 24 hours on a day where a time zone shift occurs. The duration of a specific recurrence may be modified in an exception component or simply by using an “RDATE” property of PERIOD value type.

    Examples

    Daily for 10 occurrences:

        >>> from icalendar import Event
        >>> from datetime import datetime
        >>> from zoneinfo import ZoneInfo
        >>> event = Event()
        >>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
        >>> event.add("RRULE", "FREQ=DAILY;COUNT=10")
        >>> print(event.to_ical())
        BEGIN:VEVENT
        DTSTART;TZID=America/New_York:19970902T090000
        RRULE:FREQ=DAILY;COUNT=10
        END:VEVENT
        >>> event.rrules
        [vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]

    Daily until December 24, 1997:

        >>> from icalendar import Event, vRecur
        >>> from datetime import datetime
        >>> from zoneinfo import ZoneInfo
        >>> event = Event()
        >>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
        >>> event.add("RRULE", vRecur({"FREQ": ["DAILY"]}, until=datetime(1997, 12, 24, tzinfo=ZoneInfo("UTC"))))
        >>> print(event.to_ical())
        BEGIN:VEVENT
        DTSTART;TZID=America/New_York:19970902T090000
        RRULE:FREQ=DAILY;UNTIL=19971224T000000Z
        END:VEVENT
        >>> event.rrules
        [vRecur({'FREQ': ['DAILY'], 'UNTIL': [datetime.datetime(1997, 12, 24, 0, 0, tzinfo=ZoneInfo(key='UTC'))]})]

    Note

    You cannot modify the RRULE value by modifying the result. Use `icalendar.cal.Component.add()` to add values.

    If you want to compute recurrences, have a look at Related projects.

  property sequence: int

    This property defines the revision sequence number of the calendar component within a sequence of revisions.

    Value Type:

      INTEGER

    Property Parameters:

      IANA and non-standard property parameters can be specified on this property.

    Conformance:

      The property can be specified in “VEVENT”, “VTODO”, or “VJOURNAL” calendar component.

    Description:

      When a calendar component is created, its sequence number is 0. It is monotonically incremented by the “Organizer’s” CUA each time the “Organizer” makes a significant revision to the calendar component.

      The “Organizer” includes this property in an iCalendar object that it sends to an “Attendee” to specify the current version of the calendar component.

      The “Attendee” includes this property in an iCalendar object that it sends to the “Organizer” to specify the version of the calendar component to which the “Attendee” is referring.

      A change to the sequence number is not the mechanism that an “Organizer” uses to request a response from the “Attendees”. The “RSVP” parameter on the “ATTENDEE” property is used by the “Organizer” to indicate that a response from the “Attendees” is requested.

      Recurrence instances of a recurring component MAY have different sequence numbers.

    Examples

    The following is an example of this property for a calendar component that was just created by the “Organizer”:

        >>> from icalendar import Event
        >>> event = Event()
        >>> event.sequence
        0

    The following is an example of this property for a calendar component that has been revised 10 different times by the “Organizer”:

        >>> from icalendar import Calendar
        >>> calendar = Calendar.example("issue_156_RDATE_with_PERIOD_TZID_khal")
        >>> event = calendar.events[0]
        >>> event.sequence
        10

  property start: date | datetime

    The start of the component.

    Invalid values raise an InvalidCalendar. If there is no start, we also raise an IncompleteComponent error.

    You can get the start, end and duration of an event as follows:

        >>> from datetime import datetime
        >>> from icalendar import Event
        >>> event = Event()
        >>> event.start = datetime(2021, 1, 1, 12)
        >>> event.end = datetime(2021, 1, 1, 12, 30) # 30 minutes
        >>> event.duration  # 1800 seconds == 30 minutes
        datetime.timedelta(seconds=1800)
        >>> print(event.to_ical())
        BEGIN:VEVENT
        DTSTART:20210101T120000
        DTEND:20210101T123000
        END:VEVENT

  property uid: str

    UID specifies the persistent, globally unique identifier for a component.

    We recommend using `uuid.uuid4()` to generate new values.

    Returns:

      The value of the UID property as a string or `""` if no value is set.

    Description:

      The “UID” itself MUST be a globally unique identifier. The generator of the identifier MUST guarantee that the identifier is unique.

      This is the method for correlating scheduling messages with the referenced “VEVENT”, “VTODO”, or “VJOURNAL” calendar component. The full range of calendar components specified by a recurrence set is referenced by referring to just the “UID” property value corresponding to the calendar component. The “RECURRENCE-ID” property allows the reference to an individual instance within the recurrence set.

      This property is an important method for group-scheduling applications to match requests with later replies, modifications, or deletion requests. Calendaring and scheduling applications MUST generate this property in “VEVENT”, “VTODO”, and “VJOURNAL” calendar components to assure interoperability with other group- scheduling applications. This identifier is created by the calendar system that generates an iCalendar object.

      Implementations MUST be able to receive and persist values of at least 255 octets for this property, but they MUST NOT truncate values in the middle of a UTF-8 multi-octet sequence.

      RFC 7986 states that UID can be used, for example, to identify duplicate calendar streams that a client may have been given access to. It can be used in conjunction with the “LAST-MODIFIED” property also specified on the “VCALENDAR” object to identify the most recent version of a calendar.

    Conformance:

      RFC 5545 states that the “UID” property can be specified on “VEVENT”, “VTODO”, and “VJOURNAL” calendar components. RFC 7986 modifies the definition of the “UID” property to allow it to be defined in an iCalendar object. RFC 9074 adds a “UID” property to “VALARM” components to allow a unique identifier to be specified. The value of this property can then be used to refer uniquely to the “VALARM” component.

      This property can be specified once only.

    Security:

      RFC 7986 states that UID values MUST NOT include any data that might identify a user, host, domain, or any other security- or privacy-sensitive information. It is RECOMMENDED that calendar user agents now generate “UID” values that are hex-encoded random Universally Unique Identifier (UUID) values as defined in Sections 4.4 and 4.5 of RFC 4122. You can use the `uuid` module to generate new UUIDs.

    Compatibility:

      For Alarms, `X-ALARMUID` is also considered.

    Examples

    The following is an example of such a property value: `5FC53010-1267-4F8E-BC28-1D7AE55A7C99`.

    Set the UID of a calendar:

        >>> from icalendar import Calendar
        >>> from uuid import uuid4
        >>> calendar = Calendar()
        >>> calendar.uid = uuid4()
        >>> print(calendar.to_ical())
        BEGIN:VCALENDAR
        UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
        END:VCALENDAR

class icalendar.cal.FreeBusy(*args, **kwargs)

  A “VFREEBUSY” calendar component is a grouping of component properties that represents either a request for free or busy time information, a reply to a request for free or busy time information, or a published set of busy time information.

  property uid: str

    UID specifies the persistent, globally unique identifier for a component.

    We recommend using `uuid.uuid4()` to generate new values.

    Returns:

      The value of the UID property as a string or `""` if no value is set.

    Description:

      The “UID” itself MUST be a globally unique identifier. The generator of the identifier MUST guarantee that the identifier is unique.

      This is the method for correlating scheduling messages with the referenced “VEVENT”, “VTODO”, or “VJOURNAL” calendar component. The full range of calendar components specified by a recurrence set is referenced by referring to just the “UID” property value corresponding to the calendar component. The “RECURRENCE-ID” property allows the reference to an individual instance within the recurrence set.

      This property is an important method for group-scheduling applications to match requests with later replies, modifications, or deletion requests. Calendaring and scheduling applications MUST generate this property in “VEVENT”, “VTODO”, and “VJOURNAL” calendar components to assure interoperability with other group- scheduling applications. This identifier is created by the calendar system that generates an iCalendar object.

      Implementations MUST be able to receive and persist values of at least 255 octets for this property, but they MUST NOT truncate values in the middle of a UTF-8 multi-octet sequence.

      RFC 7986 states that UID can be used, for example, to identify duplicate calendar streams that a client may have been given access to. It can be used in conjunction with the “LAST-MODIFIED” property also specified on the “VCALENDAR” object to identify the most recent version of a calendar.

    Conformance:

      RFC 5545 states that the “UID” property can be specified on “VEVENT”, “VTODO”, and “VJOURNAL” calendar components. RFC 7986 modifies the definition of the “UID” property to allow it to be defined in an iCalendar object. RFC 9074 adds a “UID” property to “VALARM” components to allow a unique identifier to be specified. The value of this property can then be used to refer uniquely to the “VALARM” component.

      This property can be specified once only.

    Security:

      RFC 7986 states that UID values MUST NOT include any data that might identify a user, host, domain, or any other security- or privacy-sensitive information. It is RECOMMENDED that calendar user agents now generate “UID” values that are hex-encoded random Universally Unique Identifier (UUID) values as defined in Sections 4.4 and 4.5 of RFC 4122. You can use the `uuid` module to generate new UUIDs.

    Compatibility:

      For Alarms, `X-ALARMUID` is also considered.

    Examples

    The following is an example of such a property value: `5FC53010-1267-4F8E-BC28-1D7AE55A7C99`.

    Set the UID of a calendar:

        >>> from icalendar import Calendar
        >>> from uuid import uuid4
        >>> calendar = Calendar()
        >>> calendar.uid = uuid4()
        >>> print(calendar.to_ical())
        BEGIN:VCALENDAR
        UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
        END:VCALENDAR

exception icalendar.cal.IncompleteComponent

  The component is missing attributes.

  The attributes are not required, otherwise this would be an InvalidCalendar. But in order to perform calculations, this attribute is required.

  This error is not raised in the UPPERCASE properties like .DTSTART, only in the lowercase computations like .start.

class icalendar.cal.Journal(*args, **kwargs)

  A descriptive text at a certain time or associated with a component.

  A “VJOURNAL” calendar component is a grouping of component properties that represent one or more descriptive text notes associated with a particular calendar date. The “DTSTART” property is used to specify the calendar date with which the journal entry is associated. Generally, it will have a DATE value data type, but it can also be used to specify a DATE-TIME value data type. Examples of a journal entry include a daily record of a legislative body or a journal entry of individual telephone contacts for the day or an ordered list of accomplishments for the day.

  property DTSTART: date | None

    The DTSTART property.

    The “DTSTART” property for a “VJOURNAL” that specifies the exact date at which the journal entry was made.

    Accepted values: datetime, date. If the attribute has invalid values, we raise InvalidCalendar. If the value is absent, we return None. You can also delete the value with del or by setting it to None.

  property categories: list[str]

    This property defines the categories for a component.

    Property Parameters:

      IANA, non-standard, and language property parameters can be specified on this property.

    Conformance:

      The property can be specified within “VEVENT”, “VTODO”, or “VJOURNAL” calendar components. Since RFC 7986 it can also be defined on a “VCALENDAR” component.

    Description:

      This property is used to specify categories or subtypes of the calendar component. The categories are useful in searching for a calendar component of a particular type and category. Within the “VEVENT”, “VTODO”, or “VJOURNAL” calendar components, more than one category can be specified as a COMMA-separated list of categories.

    Example

    Below, we add the categories to an event:

        >>> from icalendar import Event
        >>> event = Event()
        >>> event.categories = ["Work", "Meeting"]
        >>> print(event.to_ical())
        BEGIN:VEVENT
        CATEGORIES:Work,Meeting
        END:VEVENT
        >>> event.categories.append("Lecture")
        >>> event.categories == ["Work", "Meeting", "Lecture"]
        True

    Note

    At present, we do not take the LANGUAGE parameter into account.

  property color: str

    This property specifies a color used for displaying the component.

    This implements RFC 7986 `COLOR` property.

    Property Parameters:

      IANA and non-standard property parameters can be specified on this property.

    Conformance:

      This property can be specified once in an iCalendar object or in `VEVENT`, `VTODO`, or `VJOURNAL` calendar components.

    Description:

      This property specifies a color that clients MAY use when presenting the relevant data to a user. Typically, this would appear as the “background” color of events or tasks. The value is a case-insensitive color name taken from the CSS3 set of names, defined in Section 4.3 of W3C.REC-css3-color-20110607.

    Example

    `"turquoise"`, `"#ffffff"`

        >>> from icalendar import Todo
        >>> todo = Todo()
        >>> todo.color = "green"
        >>> print(todo.to_ical())
        BEGIN:VTODO
        COLOR:green
        END:VTODO

  property duration: timedelta

    timedelta(0).

    Type:

      The journal has no duration

  property end: date

    The start of the Journal.

    The “DTSTART” property is used to specify the calendar date with which the journal entry is associated.

  property exdates: list[date | datetime]

    EXDATE defines the list of DATE-TIME exceptions for recurring components.

    EXDATE is defined in RFC 5545.

    Value Type:

      The default value type for this property is DATE-TIME. The value type can be set to DATE.

    Property Parameters:

      IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

    Conformance:

      This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

    Description:

      The exception dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). When duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

      The “EXDATE” property can be used to exclude the value specified in “DTSTART”. However, in such cases, the original “DTSTART” date MUST still be maintained by the calendaring and scheduling system because the original “DTSTART” value has inherent usage dependencies by other properties such as the “RECURRENCE-ID”.

    Example

    Below, we add an exdate in a list and get the resulting list of exdates.

        >>> from icalendar import Event
        >>> from datetime import datetime
        >>> event = Event()

        # Add a list of excluded dates
        >>> event.add("EXDATE", [datetime(2025, 4, 28, 16, 5)])
        >>> event.exdates
        [datetime.datetime(2025, 4, 28, 16, 5)]

    Note

    You cannot modify the EXDATE value by modifying the result. Use `icalendar.cal.Component.add()` to add values.

    If you want to compute recurrences, have a look at Related projects.

  property rdates: list[tuple[date, None] | tuple[datetime, None] | tuple[datetime, datetime]]

    The RDATE property defines the list of DATE-TIME values for recurring components.

    RDATE is defined in RFC 5545. The return value is a list of tuples `(start, end)`.

    `start` can be a `datetime.date` or a `datetime.datetime`, with and without timezone.

    `end` is `None` if the end is not specified and a `datetime.datetime` if the end is specified.

    Value Type:

      The default value type for this property is DATE-TIME. The value type can be set to DATE or PERIOD.

    Property Parameters:

      IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

    Conformance:

      This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

    Description:

      This property can appear along with the “RRULE” property to define an aggregate set of repeating occurrences. When they both appear in a recurring component, the recurrence instances are defined by the union of occurrences defined by both the “RDATE” and “RRULE”.

      The recurrence dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

    Example

    Below, we set one RDATE in a list and get the resulting tuple of start and end.

        >>> from icalendar import Event
        >>> from datetime import datetime
        >>> event = Event()

        # Add a list of recurrence dates
        >>> event.add("RDATE", [datetime(2025, 4, 28, 16, 5)])
        >>> event.rdates
        [(datetime.datetime(2025, 4, 28, 16, 5), None)]

    Note

    You cannot modify the RDATE value by modifying the result. Use `icalendar.cal.Component.add()` to add values.

    If you want to compute recurrences, have a look at Related projects.

  property rrules: list[vRecur]

    RRULE defines a rule or repeating pattern for recurring components.

    RRULE is defined in RFC 5545. RFC 7529 adds the `SKIP` parameter `icalendar.prop.vSkip`.

    Property Parameters:

      IANA and non-standard property parameters can be specified on this property.

    Conformance:

      This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component, but it SHOULD NOT be specified more than once. The recurrence set generated with multiple “RRULE” properties is undefined.

    Description:

      The recurrence rule, if specified, is used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD be synchronized with the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value not synchronized with the recurrence rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE- TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

      The “DTSTART” property specified within the iCalendar object defines the first instance of the recurrence. In most cases, a “DTSTART” property of DATE-TIME value type used with a recurrence rule, should be specified as a date with local time and time zone reference to make sure all the recurrence instances start at the same local time regardless of time zone changes.

      If the duration of the recurring component is specified with the “DTEND” or “DUE” property, then the same exact duration will apply to all the members of the generated recurrence set. Else, if the duration of the recurring component is specified with the “DURATION” property, then the same nominal duration will apply to all the members of the generated recurrence set and the exact duration of each recurrence instance will depend on its specific start time. For example, recurrence instances of a nominal duration of one day will have an exact duration of more or less than 24 hours on a day where a time zone shift occurs. The duration of a specific recurrence may be modified in an exception component or simply by using an “RDATE” property of PERIOD value type.

    Examples

    Daily for 10 occurrences:

        >>> from icalendar import Event
        >>> from datetime import datetime
        >>> from zoneinfo import ZoneInfo
        >>> event = Event()
        >>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
        >>> event.add("RRULE", "FREQ=DAILY;COUNT=10")
        >>> print(event.to_ical())
        BEGIN:VEVENT
        DTSTART;TZID=America/New_York:19970902T090000
        RRULE:FREQ=DAILY;COUNT=10
        END:VEVENT
        >>> event.rrules
        [vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]

    Daily until December 24, 1997:

        >>> from icalendar import Event, vRecur
        >>> from datetime import datetime
        >>> from zoneinfo import ZoneInfo
        >>> event = Event()
        >>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
        >>> event.add("RRULE", vRecur({"FREQ": ["DAILY"]}, until=datetime(1997, 12, 24, tzinfo=ZoneInfo("UTC"))))
        >>> print(event.to_ical())
        BEGIN:VEVENT
        DTSTART;TZID=America/New_York:19970902T090000
        RRULE:FREQ=DAILY;UNTIL=19971224T000000Z
        END:VEVENT
        >>> event.rrules
        [vRecur({'FREQ': ['DAILY'], 'UNTIL': [datetime.datetime(1997, 12, 24, 0, 0, tzinfo=ZoneInfo(key='UTC'))]})]

    Note

    You cannot modify the RRULE value by modifying the result. Use `icalendar.cal.Component.add()` to add values.

    If you want to compute recurrences, have a look at Related projects.

  property sequence: int

    This property defines the revision sequence number of the calendar component within a sequence of revisions.

    Value Type:

      INTEGER

    Property Parameters:

      IANA and non-standard property parameters can be specified on this property.

    Conformance:

      The property can be specified in “VEVENT”, “VTODO”, or “VJOURNAL” calendar component.

    Description:

      When a calendar component is created, its sequence number is 0. It is monotonically incremented by the “Organizer’s” CUA each time the “Organizer” makes a significant revision to the calendar component.

      The “Organizer” includes this property in an iCalendar object that it sends to an “Attendee” to specify the current version of the calendar component.

      The “Attendee” includes this property in an iCalendar object that it sends to the “Organizer” to specify the version of the calendar component to which the “Attendee” is referring.

      A change to the sequence number is not the mechanism that an “Organizer” uses to request a response from the “Attendees”. The “RSVP” parameter on the “ATTENDEE” property is used by the “Organizer” to indicate that a response from the “Attendees” is requested.

      Recurrence instances of a recurring component MAY have different sequence numbers.

    Examples

    The following is an example of this property for a calendar component that was just created by the “Organizer”:

        >>> from icalendar import Event
        >>> event = Event()
        >>> event.sequence
        0

    The following is an example of this property for a calendar component that has been revised 10 different times by the “Organizer”:

        >>> from icalendar import Calendar
        >>> calendar = Calendar.example("issue_156_RDATE_with_PERIOD_TZID_khal")
        >>> event = calendar.events[0]
        >>> event.sequence
        10

  property start: date

    The start of the Journal.

    The “DTSTART” property is used to specify the calendar date with which the journal entry is associated.

  property uid: str

    UID specifies the persistent, globally unique identifier for a component.

    We recommend using `uuid.uuid4()` to generate new values.

    Returns:

      The value of the UID property as a string or `""` if no value is set.

    Description:

      The “UID” itself MUST be a globally unique identifier. The generator of the identifier MUST guarantee that the identifier is unique.

      This is the method for correlating scheduling messages with the referenced “VEVENT”, “VTODO”, or “VJOURNAL” calendar component. The full range of calendar components specified by a recurrence set is referenced by referring to just the “UID” property value corresponding to the calendar component. The “RECURRENCE-ID” property allows the reference to an individual instance within the recurrence set.

      This property is an important method for group-scheduling applications to match requests with later replies, modifications, or deletion requests. Calendaring and scheduling applications MUST generate this property in “VEVENT”, “VTODO”, and “VJOURNAL” calendar components to assure interoperability with other group- scheduling applications. This identifier is created by the calendar system that generates an iCalendar object.

      Implementations MUST be able to receive and persist values of at least 255 octets for this property, but they MUST NOT truncate values in the middle of a UTF-8 multi-octet sequence.

      RFC 7986 states that UID can be used, for example, to identify duplicate calendar streams that a client may have been given access to. It can be used in conjunction with the “LAST-MODIFIED” property also specified on the “VCALENDAR” object to identify the most recent version of a calendar.

    Conformance:

      RFC 5545 states that the “UID” property can be specified on “VEVENT”, “VTODO”, and “VJOURNAL” calendar components. RFC 7986 modifies the definition of the “UID” property to allow it to be defined in an iCalendar object. RFC 9074 adds a “UID” property to “VALARM” components to allow a unique identifier to be specified. The value of this property can then be used to refer uniquely to the “VALARM” component.

      This property can be specified once only.

    Security:

      RFC 7986 states that UID values MUST NOT include any data that might identify a user, host, domain, or any other security- or privacy-sensitive information. It is RECOMMENDED that calendar user agents now generate “UID” values that are hex-encoded random Universally Unique Identifier (UUID) values as defined in Sections 4.4 and 4.5 of RFC 4122. You can use the `uuid` module to generate new UUIDs.

    Compatibility:

      For Alarms, `X-ALARMUID` is also considered.

    Examples

    The following is an example of such a property value: `5FC53010-1267-4F8E-BC28-1D7AE55A7C99`.

    Set the UID of a calendar:

        >>> from icalendar import Calendar
        >>> from uuid import uuid4
        >>> calendar = Calendar()
        >>> calendar.uid = uuid4()
        >>> print(calendar.to_ical())
        BEGIN:VCALENDAR
        UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
        END:VCALENDAR

class icalendar.cal.Timezone(*args, **kwargs)

  A “VTIMEZONE” calendar component is a grouping of component properties that defines a time zone. It is used to describe the way in which a time zone changes its offset from UTC over time.

  property daylight: list[TimezoneDaylight]

    The DAYLIGHT subcomponents as a list.

    These are for the daylight saving time.

  classmethod example(name: str = 'pacific_fiji') → Calendar

    Return the timezone example with the given name.

  classmethod from_tzid(tzid: str, tzp: TZP = TZP('zoneinfo'), first_date: date = datetime.date(1970, 1, 1), last_date: date = datetime.date(2038, 1, 1)) → Timezone

    Create a VTIMEZONE from a tzid like `"Europe/Berlin"`.

    Parameters:

      - tzid – the id of the timezone

      - tzp – the timezone provider

      - first_date – a datetime that is earlier than anything that happens in the calendar

      - last_date – a datetime that is later than anything that happens in the calendar

    Raises:

      ValueError – If the tzid is unknown.

        >>> from icalendar import Timezone
        >>> tz = Timezone.from_tzid("Europe/Berlin")
        >>> print(tz.to_ical()[:36])
        BEGIN:VTIMEZONE
        TZID:Europe/Berlin

    Note

    This can take some time. Please cache the results.

  classmethod from_tzinfo(timezone: tzinfo, tzid: str | None = None, first_date: date = datetime.date(1970, 1, 1), last_date: date = datetime.date(2038, 1, 1)) → Timezone

    Return a VTIMEZONE component from a timezone object.

    This works with pytz and zoneinfo and any other timezone. The offsets are calculated from the tzinfo object.

    Parameters:

    Parameters:

      - tzinfo – the timezone object

      - tzid – the tzid for this timezone. If None, it will be extracted from the tzinfo.

      - first_date – a datetime that is earlier than anything that happens in the calendar

      - last_date – a datetime that is later than anything that happens in the calendar

    Raises:

      ValueError – If we have no tzid and cannot extract one.

    Note

    This can take some time. Please cache the results.

  get_transitions() → Tuple[List[datetime], List[Tuple[timedelta, timedelta, str]]]

    Return a tuple of (transition_times, transition_info)

    - transition_times = [datetime, …]

    - transition_info = [(TZOFFSETTO, dts_offset, tzname)]

  property standard: list[TimezoneStandard]

    The STANDARD subcomponents as a list.

  to_tz(tzp: TZP = TZP('zoneinfo'), lookup_tzid: bool = True)

    convert this VTIMEZONE component to a timezone object

    Parameters:

      - tzp – timezone provider to use

      - lookup_tzid – whether to use the TZID property to look up existing timezone definitions with tzp. If it is False, a new timezone will be created. If it is True, the existing timezone will be used if it exists, otherwise a new timezone will be created.

  property tz_name: str

    Return the name of the timezone component.

    Please note that the names of the timezone are different from this name and may change with winter/summer time.

class icalendar.cal.TimezoneDaylight(*args, **kwargs)

  The “DAYLIGHT” sub-component of “VTIMEZONE” defines the daylight saving time offset from UTC for a time zone. It represents a time zone’s daylight saving time, typically used during summer months in locations that observe Daylight Saving Time.

  property DTSTART: datetime | None

    The DTSTART property.

    The mandatory “DTSTART” property gives the effective onset date

      and local time for the time zone sub-component definition. “DTSTART” in this usage MUST be specified as a date with a local time value.

    Accepted values: datetime. If the attribute has invalid values, we raise InvalidCalendar. If the value is absent, we return None. You can also delete the value with del or by setting it to None.

  property TZOFFSETFROM: timedelta | None

    The TZOFFSETFROM property.

    The mandatory “TZOFFSETFROM” property gives the UTC offset that is

      in use when the onset of this time zone observance begins. “TZOFFSETFROM” is combined with “DTSTART” to define the effective onset for the time zone sub-component definition. For example, the following represents the time at which the observance of Standard Time took effect in Fall 1967 for New York City:

      > DTSTART:19671029T020000 TZOFFSETFROM:-0400

    Accepted values: timedelta. If the attribute has invalid values, we raise InvalidCalendar. If the value is absent, we return None. You can also delete the value with del or by setting it to None.

  property TZOFFSETTO: timedelta | None

    The TZOFFSETTO property.

    The mandatory “TZOFFSETTO” property gives the UTC offset for the

      time zone sub-component (Standard Time or Daylight Saving Time) when this observance is in use.

    Accepted values: timedelta. If the attribute has invalid values, we raise InvalidCalendar. If the value is absent, we return None. You can also delete the value with del or by setting it to None.

  property exdates: list[date | datetime]

    EXDATE defines the list of DATE-TIME exceptions for recurring components.

    EXDATE is defined in RFC 5545.

    Value Type:

      The default value type for this property is DATE-TIME. The value type can be set to DATE.

    Property Parameters:

      IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

    Conformance:

      This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

    Description:

      The exception dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). When duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

      The “EXDATE” property can be used to exclude the value specified in “DTSTART”. However, in such cases, the original “DTSTART” date MUST still be maintained by the calendaring and scheduling system because the original “DTSTART” value has inherent usage dependencies by other properties such as the “RECURRENCE-ID”.

    Example

    Below, we add an exdate in a list and get the resulting list of exdates.

        >>> from icalendar import Event
        >>> from datetime import datetime
        >>> event = Event()

        # Add a list of excluded dates
        >>> event.add("EXDATE", [datetime(2025, 4, 28, 16, 5)])
        >>> event.exdates
        [datetime.datetime(2025, 4, 28, 16, 5)]

    Note

    You cannot modify the EXDATE value by modifying the result. Use `icalendar.cal.Component.add()` to add values.

    If you want to compute recurrences, have a look at Related projects.

  property rdates: list[tuple[date, None] | tuple[datetime, None] | tuple[datetime, datetime]]

    The RDATE property defines the list of DATE-TIME values for recurring components.

    RDATE is defined in RFC 5545. The return value is a list of tuples `(start, end)`.

    `start` can be a `datetime.date` or a `datetime.datetime`, with and without timezone.

    `end` is `None` if the end is not specified and a `datetime.datetime` if the end is specified.

    Value Type:

      The default value type for this property is DATE-TIME. The value type can be set to DATE or PERIOD.

    Property Parameters:

      IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

    Conformance:

      This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

    Description:

      This property can appear along with the “RRULE” property to define an aggregate set of repeating occurrences. When they both appear in a recurring component, the recurrence instances are defined by the union of occurrences defined by both the “RDATE” and “RRULE”.

      The recurrence dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

    Example

    Below, we set one RDATE in a list and get the resulting tuple of start and end.

        >>> from icalendar import Event
        >>> from datetime import datetime
        >>> event = Event()

        # Add a list of recurrence dates
        >>> event.add("RDATE", [datetime(2025, 4, 28, 16, 5)])
        >>> event.rdates
        [(datetime.datetime(2025, 4, 28, 16, 5), None)]

    Note

    You cannot modify the RDATE value by modifying the result. Use `icalendar.cal.Component.add()` to add values.

    If you want to compute recurrences, have a look at Related projects.

  property rrules: list[vRecur]

    RRULE defines a rule or repeating pattern for recurring components.

    RRULE is defined in RFC 5545. RFC 7529 adds the `SKIP` parameter `icalendar.prop.vSkip`.

    Property Parameters:

      IANA and non-standard property parameters can be specified on this property.

    Conformance:

      This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component, but it SHOULD NOT be specified more than once. The recurrence set generated with multiple “RRULE” properties is undefined.

    Description:

      The recurrence rule, if specified, is used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD be synchronized with the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value not synchronized with the recurrence rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE- TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

      The “DTSTART” property specified within the iCalendar object defines the first instance of the recurrence. In most cases, a “DTSTART” property of DATE-TIME value type used with a recurrence rule, should be specified as a date with local time and time zone reference to make sure all the recurrence instances start at the same local time regardless of time zone changes.

      If the duration of the recurring component is specified with the “DTEND” or “DUE” property, then the same exact duration will apply to all the members of the generated recurrence set. Else, if the duration of the recurring component is specified with the “DURATION” property, then the same nominal duration will apply to all the members of the generated recurrence set and the exact duration of each recurrence instance will depend on its specific start time. For example, recurrence instances of a nominal duration of one day will have an exact duration of more or less than 24 hours on a day where a time zone shift occurs. The duration of a specific recurrence may be modified in an exception component or simply by using an “RDATE” property of PERIOD value type.

    Examples

    Daily for 10 occurrences:

        >>> from icalendar import Event
        >>> from datetime import datetime
        >>> from zoneinfo import ZoneInfo
        >>> event = Event()
        >>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
        >>> event.add("RRULE", "FREQ=DAILY;COUNT=10")
        >>> print(event.to_ical())
        BEGIN:VEVENT
        DTSTART;TZID=America/New_York:19970902T090000
        RRULE:FREQ=DAILY;COUNT=10
        END:VEVENT
        >>> event.rrules
        [vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]

    Daily until December 24, 1997:

        >>> from icalendar import Event, vRecur
        >>> from datetime import datetime
        >>> from zoneinfo import ZoneInfo
        >>> event = Event()
        >>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
        >>> event.add("RRULE", vRecur({"FREQ": ["DAILY"]}, until=datetime(1997, 12, 24, tzinfo=ZoneInfo("UTC"))))
        >>> print(event.to_ical())
        BEGIN:VEVENT
        DTSTART;TZID=America/New_York:19970902T090000
        RRULE:FREQ=DAILY;UNTIL=19971224T000000Z
        END:VEVENT
        >>> event.rrules
        [vRecur({'FREQ': ['DAILY'], 'UNTIL': [datetime.datetime(1997, 12, 24, 0, 0, tzinfo=ZoneInfo(key='UTC'))]})]

    Note

    You cannot modify the RRULE value by modifying the result. Use `icalendar.cal.Component.add()` to add values.

    If you want to compute recurrences, have a look at Related projects.

class icalendar.cal.TimezoneStandard(*args, **kwargs)

  The “STANDARD” sub-component of “VTIMEZONE” defines the standard time offset from UTC for a time zone. It represents a time zone’s standard time, typically used during winter months in locations that observe Daylight Saving Time.

  property DTSTART: datetime | None

    The DTSTART property.

    The mandatory “DTSTART” property gives the effective onset date

      and local time for the time zone sub-component definition. “DTSTART” in this usage MUST be specified as a date with a local time value.

    Accepted values: datetime. If the attribute has invalid values, we raise InvalidCalendar. If the value is absent, we return None. You can also delete the value with del or by setting it to None.

  property TZOFFSETFROM: timedelta | None

    The TZOFFSETFROM property.

    The mandatory “TZOFFSETFROM” property gives the UTC offset that is

      in use when the onset of this time zone observance begins. “TZOFFSETFROM” is combined with “DTSTART” to define the effective onset for the time zone sub-component definition. For example, the following represents the time at which the observance of Standard Time took effect in Fall 1967 for New York City:

      > DTSTART:19671029T020000 TZOFFSETFROM:-0400

    Accepted values: timedelta. If the attribute has invalid values, we raise InvalidCalendar. If the value is absent, we return None. You can also delete the value with del or by setting it to None.

  property TZOFFSETTO: timedelta | None

    The TZOFFSETTO property.

    The mandatory “TZOFFSETTO” property gives the UTC offset for the

      time zone sub-component (Standard Time or Daylight Saving Time) when this observance is in use.

    Accepted values: timedelta. If the attribute has invalid values, we raise InvalidCalendar. If the value is absent, we return None. You can also delete the value with del or by setting it to None.

  property exdates: list[date | datetime]

    EXDATE defines the list of DATE-TIME exceptions for recurring components.

    EXDATE is defined in RFC 5545.

    Value Type:

      The default value type for this property is DATE-TIME. The value type can be set to DATE.

    Property Parameters:

      IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

    Conformance:

      This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

    Description:

      The exception dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). When duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

      The “EXDATE” property can be used to exclude the value specified in “DTSTART”. However, in such cases, the original “DTSTART” date MUST still be maintained by the calendaring and scheduling system because the original “DTSTART” value has inherent usage dependencies by other properties such as the “RECURRENCE-ID”.

    Example

    Below, we add an exdate in a list and get the resulting list of exdates.

        >>> from icalendar import Event
        >>> from datetime import datetime
        >>> event = Event()

        # Add a list of excluded dates
        >>> event.add("EXDATE", [datetime(2025, 4, 28, 16, 5)])
        >>> event.exdates
        [datetime.datetime(2025, 4, 28, 16, 5)]

    Note

    You cannot modify the EXDATE value by modifying the result. Use `icalendar.cal.Component.add()` to add values.

    If you want to compute recurrences, have a look at Related projects.

  property rdates: list[tuple[date, None] | tuple[datetime, None] | tuple[datetime, datetime]]

    The RDATE property defines the list of DATE-TIME values for recurring components.

    RDATE is defined in RFC 5545. The return value is a list of tuples `(start, end)`.

    `start` can be a `datetime.date` or a `datetime.datetime`, with and without timezone.

    `end` is `None` if the end is not specified and a `datetime.datetime` if the end is specified.

    Value Type:

      The default value type for this property is DATE-TIME. The value type can be set to DATE or PERIOD.

    Property Parameters:

      IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

    Conformance:

      This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

    Description:

      This property can appear along with the “RRULE” property to define an aggregate set of repeating occurrences. When they both appear in a recurring component, the recurrence instances are defined by the union of occurrences defined by both the “RDATE” and “RRULE”.

      The recurrence dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

    Example

    Below, we set one RDATE in a list and get the resulting tuple of start and end.

        >>> from icalendar import Event
        >>> from datetime import datetime
        >>> event = Event()

        # Add a list of recurrence dates
        >>> event.add("RDATE", [datetime(2025, 4, 28, 16, 5)])
        >>> event.rdates
        [(datetime.datetime(2025, 4, 28, 16, 5), None)]

    Note

    You cannot modify the RDATE value by modifying the result. Use `icalendar.cal.Component.add()` to add values.

    If you want to compute recurrences, have a look at Related projects.

  property rrules: list[vRecur]

    RRULE defines a rule or repeating pattern for recurring components.

    RRULE is defined in RFC 5545. RFC 7529 adds the `SKIP` parameter `icalendar.prop.vSkip`.

    Property Parameters:

      IANA and non-standard property parameters can be specified on this property.

    Conformance:

      This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component, but it SHOULD NOT be specified more than once. The recurrence set generated with multiple “RRULE” properties is undefined.

    Description:

      The recurrence rule, if specified, is used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD be synchronized with the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value not synchronized with the recurrence rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE- TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

      The “DTSTART” property specified within the iCalendar object defines the first instance of the recurrence. In most cases, a “DTSTART” property of DATE-TIME value type used with a recurrence rule, should be specified as a date with local time and time zone reference to make sure all the recurrence instances start at the same local time regardless of time zone changes.

      If the duration of the recurring component is specified with the “DTEND” or “DUE” property, then the same exact duration will apply to all the members of the generated recurrence set. Else, if the duration of the recurring component is specified with the “DURATION” property, then the same nominal duration will apply to all the members of the generated recurrence set and the exact duration of each recurrence instance will depend on its specific start time. For example, recurrence instances of a nominal duration of one day will have an exact duration of more or less than 24 hours on a day where a time zone shift occurs. The duration of a specific recurrence may be modified in an exception component or simply by using an “RDATE” property of PERIOD value type.

    Examples

    Daily for 10 occurrences:

        >>> from icalendar import Event
        >>> from datetime import datetime
        >>> from zoneinfo import ZoneInfo
        >>> event = Event()
        >>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
        >>> event.add("RRULE", "FREQ=DAILY;COUNT=10")
        >>> print(event.to_ical())
        BEGIN:VEVENT
        DTSTART;TZID=America/New_York:19970902T090000
        RRULE:FREQ=DAILY;COUNT=10
        END:VEVENT
        >>> event.rrules
        [vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]

    Daily until December 24, 1997:

        >>> from icalendar import Event, vRecur
        >>> from datetime import datetime
        >>> from zoneinfo import ZoneInfo
        >>> event = Event()
        >>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
        >>> event.add("RRULE", vRecur({"FREQ": ["DAILY"]}, until=datetime(1997, 12, 24, tzinfo=ZoneInfo("UTC"))))
        >>> print(event.to_ical())
        BEGIN:VEVENT
        DTSTART;TZID=America/New_York:19970902T090000
        RRULE:FREQ=DAILY;UNTIL=19971224T000000Z
        END:VEVENT
        >>> event.rrules
        [vRecur({'FREQ': ['DAILY'], 'UNTIL': [datetime.datetime(1997, 12, 24, 0, 0, tzinfo=ZoneInfo(key='UTC'))]})]

    Note

    You cannot modify the RRULE value by modifying the result. Use `icalendar.cal.Component.add()` to add values.

    If you want to compute recurrences, have a look at Related projects.

class icalendar.cal.Todo(*args, **kwargs)

  A “VTODO” calendar component is a grouping of component properties that represents an action item or assignment. For example, it can be used to represent an item of work assigned to an individual, such as “Prepare for the upcoming conference seminar on Internet Calendaring”.

  property DTSTART: date | None

    The DTSTART property.

    The “DTSTART” property for a “VTODO” specifies the inclusive start of the Todo.

    Accepted values: datetime, date. If the attribute has invalid values, we raise InvalidCalendar. If the value is absent, we return None. You can also delete the value with del or by setting it to None.

  property DUE: date | None

    The DUE property.

    The “DUE” property for a “VTODO” calendar component specifies the non-inclusive end of the Todo.

    Accepted values: datetime, date. If the attribute has invalid values, we raise InvalidCalendar. If the value is absent, we return None. You can also delete the value with del or by setting it to None.

  property DURATION: timedelta | None

    The DURATION property.

    The “DTSTART” property for a “VTODO” specifies the inclusive start of the event. The “DURATION” property in conjunction with the DTSTART property for a “VTODO” calendar component specifies the non-inclusive end of the event.

    If you would like to calculate the duration of a VTODO, do not use this. Instead use the duration property (lower case).

  property X_MOZ_LASTACK: datetime | None

    The X-MOZ-LASTACK property. datetime in UTC

    All values will be converted to a datetime in UTC. Thunderbird: Alarms before this time are acknowledged.

  property X_MOZ_SNOOZE_TIME: datetime | None

    The X-MOZ-SNOOZE-TIME property. datetime in UTC

    All values will be converted to a datetime in UTC. Thunderbird: Alarms before this time are snoozed.

  property alarms: Alarms

    Compute the alarm times for this component.

        >>> from datetime import datetime
        >>> from icalendar import Todo
        >>> todo = Todo()  # empty without alarms
        >>> todo.start = datetime(2024, 10, 26, 10, 21)
        >>> len(todo.alarms.times)
        0

    Note that this only uses DTSTART and DUE, but ignores RDATE, EXDATE, and RRULE properties.

  property categories: list[str]

    This property defines the categories for a component.

    Property Parameters:

      IANA, non-standard, and language property parameters can be specified on this property.

    Conformance:

      The property can be specified within “VEVENT”, “VTODO”, or “VJOURNAL” calendar components. Since RFC 7986 it can also be defined on a “VCALENDAR” component.

    Description:

      This property is used to specify categories or subtypes of the calendar component. The categories are useful in searching for a calendar component of a particular type and category. Within the “VEVENT”, “VTODO”, or “VJOURNAL” calendar components, more than one category can be specified as a COMMA-separated list of categories.

    Example

    Below, we add the categories to an event:

        >>> from icalendar import Event
        >>> event = Event()
        >>> event.categories = ["Work", "Meeting"]
        >>> print(event.to_ical())
        BEGIN:VEVENT
        CATEGORIES:Work,Meeting
        END:VEVENT
        >>> event.categories.append("Lecture")
        >>> event.categories == ["Work", "Meeting", "Lecture"]
        True

    Note

    At present, we do not take the LANGUAGE parameter into account.

  property color: str

    This property specifies a color used for displaying the component.

    This implements RFC 7986 `COLOR` property.

    Property Parameters:

      IANA and non-standard property parameters can be specified on this property.

    Conformance:

      This property can be specified once in an iCalendar object or in `VEVENT`, `VTODO`, or `VJOURNAL` calendar components.

    Description:

      This property specifies a color that clients MAY use when presenting the relevant data to a user. Typically, this would appear as the “background” color of events or tasks. The value is a case-insensitive color name taken from the CSS3 set of names, defined in Section 4.3 of W3C.REC-css3-color-20110607.

    Example

    `"turquoise"`, `"#ffffff"`

        >>> from icalendar import Todo
        >>> todo = Todo()
        >>> todo.color = "green"
        >>> print(todo.to_ical())
        BEGIN:VTODO
        COLOR:green
        END:VTODO

  property duration: timedelta

    The duration of the VTODO.

    This duration is calculated from the start and end of the Todo. You cannot set the duration as it is unclear what happens to start and end.

  property end: date | datetime

    The end of the component.

    Invalid values raise an InvalidCalendar error. If there is no end, we also raise an IncompleteComponent error.

  property exdates: list[date | datetime]

    EXDATE defines the list of DATE-TIME exceptions for recurring components.

    EXDATE is defined in RFC 5545.

    Value Type:

      The default value type for this property is DATE-TIME. The value type can be set to DATE.

    Property Parameters:

      IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

    Conformance:

      This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

    Description:

      The exception dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). When duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

      The “EXDATE” property can be used to exclude the value specified in “DTSTART”. However, in such cases, the original “DTSTART” date MUST still be maintained by the calendaring and scheduling system because the original “DTSTART” value has inherent usage dependencies by other properties such as the “RECURRENCE-ID”.

    Example

    Below, we add an exdate in a list and get the resulting list of exdates.

        >>> from icalendar import Event
        >>> from datetime import datetime
        >>> event = Event()

        # Add a list of excluded dates
        >>> event.add("EXDATE", [datetime(2025, 4, 28, 16, 5)])
        >>> event.exdates
        [datetime.datetime(2025, 4, 28, 16, 5)]

    Note

    You cannot modify the EXDATE value by modifying the result. Use `icalendar.cal.Component.add()` to add values.

    If you want to compute recurrences, have a look at Related projects.

  property rdates: list[tuple[date, None] | tuple[datetime, None] | tuple[datetime, datetime]]

    The RDATE property defines the list of DATE-TIME values for recurring components.

    RDATE is defined in RFC 5545. The return value is a list of tuples `(start, end)`.

    `start` can be a `datetime.date` or a `datetime.datetime`, with and without timezone.

    `end` is `None` if the end is not specified and a `datetime.datetime` if the end is specified.

    Value Type:

      The default value type for this property is DATE-TIME. The value type can be set to DATE or PERIOD.

    Property Parameters:

      IANA, non-standard, value data type, and time zone identifier property parameters can be specified on this property.

    Conformance:

      This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component.

    Description:

      This property can appear along with the “RRULE” property to define an aggregate set of repeating occurrences. When they both appear in a recurring component, the recurrence instances are defined by the union of occurrences defined by both the “RDATE” and “RRULE”.

      The recurrence dates, if specified, are used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE-TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

    Example

    Below, we set one RDATE in a list and get the resulting tuple of start and end.

        >>> from icalendar import Event
        >>> from datetime import datetime
        >>> event = Event()

        # Add a list of recurrence dates
        >>> event.add("RDATE", [datetime(2025, 4, 28, 16, 5)])
        >>> event.rdates
        [(datetime.datetime(2025, 4, 28, 16, 5), None)]

    Note

    You cannot modify the RDATE value by modifying the result. Use `icalendar.cal.Component.add()` to add values.

    If you want to compute recurrences, have a look at Related projects.

  property rrules: list[vRecur]

    RRULE defines a rule or repeating pattern for recurring components.

    RRULE is defined in RFC 5545. RFC 7529 adds the `SKIP` parameter `icalendar.prop.vSkip`.

    Property Parameters:

      IANA and non-standard property parameters can be specified on this property.

    Conformance:

      This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component, but it SHOULD NOT be specified more than once. The recurrence set generated with multiple “RRULE” properties is undefined.

    Description:

      The recurrence rule, if specified, is used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD be synchronized with the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value not synchronized with the recurrence rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE- TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

      The “DTSTART” property specified within the iCalendar object defines the first instance of the recurrence. In most cases, a “DTSTART” property of DATE-TIME value type used with a recurrence rule, should be specified as a date with local time and time zone reference to make sure all the recurrence instances start at the same local time regardless of time zone changes.

      If the duration of the recurring component is specified with the “DTEND” or “DUE” property, then the same exact duration will apply to all the members of the generated recurrence set. Else, if the duration of the recurring component is specified with the “DURATION” property, then the same nominal duration will apply to all the members of the generated recurrence set and the exact duration of each recurrence instance will depend on its specific start time. For example, recurrence instances of a nominal duration of one day will have an exact duration of more or less than 24 hours on a day where a time zone shift occurs. The duration of a specific recurrence may be modified in an exception component or simply by using an “RDATE” property of PERIOD value type.

    Examples

    Daily for 10 occurrences:

        >>> from icalendar import Event
        >>> from datetime import datetime
        >>> from zoneinfo import ZoneInfo
        >>> event = Event()
        >>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
        >>> event.add("RRULE", "FREQ=DAILY;COUNT=10")
        >>> print(event.to_ical())
        BEGIN:VEVENT
        DTSTART;TZID=America/New_York:19970902T090000
        RRULE:FREQ=DAILY;COUNT=10
        END:VEVENT
        >>> event.rrules
        [vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]

    Daily until December 24, 1997:

        >>> from icalendar import Event, vRecur
        >>> from datetime import datetime
        >>> from zoneinfo import ZoneInfo
        >>> event = Event()
        >>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
        >>> event.add("RRULE", vRecur({"FREQ": ["DAILY"]}, until=datetime(1997, 12, 24, tzinfo=ZoneInfo("UTC"))))
        >>> print(event.to_ical())
        BEGIN:VEVENT
        DTSTART;TZID=America/New_York:19970902T090000
        RRULE:FREQ=DAILY;UNTIL=19971224T000000Z
        END:VEVENT
        >>> event.rrules
        [vRecur({'FREQ': ['DAILY'], 'UNTIL': [datetime.datetime(1997, 12, 24, 0, 0, tzinfo=ZoneInfo(key='UTC'))]})]

    Note

    You cannot modify the RRULE value by modifying the result. Use `icalendar.cal.Component.add()` to add values.

    If you want to compute recurrences, have a look at Related projects.

  property sequence: int

    This property defines the revision sequence number of the calendar component within a sequence of revisions.

    Value Type:

      INTEGER

    Property Parameters:

      IANA and non-standard property parameters can be specified on this property.

    Conformance:

      The property can be specified in “VEVENT”, “VTODO”, or “VJOURNAL” calendar component.

    Description:

      When a calendar component is created, its sequence number is 0. It is monotonically incremented by the “Organizer’s” CUA each time the “Organizer” makes a significant revision to the calendar component.

      The “Organizer” includes this property in an iCalendar object that it sends to an “Attendee” to specify the current version of the calendar component.

      The “Attendee” includes this property in an iCalendar object that it sends to the “Organizer” to specify the version of the calendar component to which the “Attendee” is referring.

      A change to the sequence number is not the mechanism that an “Organizer” uses to request a response from the “Attendees”. The “RSVP” parameter on the “ATTENDEE” property is used by the “Organizer” to indicate that a response from the “Attendees” is requested.

      Recurrence instances of a recurring component MAY have different sequence numbers.

    Examples

    The following is an example of this property for a calendar component that was just created by the “Organizer”:

        >>> from icalendar import Event
        >>> event = Event()
        >>> event.sequence
        0

    The following is an example of this property for a calendar component that has been revised 10 different times by the “Organizer”:

        >>> from icalendar import Calendar
        >>> calendar = Calendar.example("issue_156_RDATE_with_PERIOD_TZID_khal")
        >>> event = calendar.events[0]
        >>> event.sequence
        10

  property start: date | datetime

    The start of the VTODO.

    Invalid values raise an InvalidCalendar. If there is no start, we also raise an IncompleteComponent error.

    You can get the start, end and duration of a Todo as follows:

        >>> from datetime import datetime
        >>> from icalendar import Todo
        >>> todo = Todo()
        >>> todo.start = datetime(2021, 1, 1, 12)
        >>> todo.end = datetime(2021, 1, 1, 12, 30) # 30 minutes
        >>> todo.duration  # 1800 seconds == 30 minutes
        datetime.timedelta(seconds=1800)
        >>> print(todo.to_ical())
        BEGIN:VTODO
        DTSTART:20210101T120000
        DUE:20210101T123000
        END:VTODO

  property uid: str

    UID specifies the persistent, globally unique identifier for a component.

    We recommend using `uuid.uuid4()` to generate new values.

    Returns:

      The value of the UID property as a string or `""` if no value is set.

    Description:

      The “UID” itself MUST be a globally unique identifier. The generator of the identifier MUST guarantee that the identifier is unique.

      This is the method for correlating scheduling messages with the referenced “VEVENT”, “VTODO”, or “VJOURNAL” calendar component. The full range of calendar components specified by a recurrence set is referenced by referring to just the “UID” property value corresponding to the calendar component. The “RECURRENCE-ID” property allows the reference to an individual instance within the recurrence set.

      This property is an important method for group-scheduling applications to match requests with later replies, modifications, or deletion requests. Calendaring and scheduling applications MUST generate this property in “VEVENT”, “VTODO”, and “VJOURNAL” calendar components to assure interoperability with other group- scheduling applications. This identifier is created by the calendar system that generates an iCalendar object.

      Implementations MUST be able to receive and persist values of at least 255 octets for this property, but they MUST NOT truncate values in the middle of a UTF-8 multi-octet sequence.

      RFC 7986 states that UID can be used, for example, to identify duplicate calendar streams that a client may have been given access to. It can be used in conjunction with the “LAST-MODIFIED” property also specified on the “VCALENDAR” object to identify the most recent version of a calendar.

    Conformance:

      RFC 5545 states that the “UID” property can be specified on “VEVENT”, “VTODO”, and “VJOURNAL” calendar components. RFC 7986 modifies the definition of the “UID” property to allow it to be defined in an iCalendar object. RFC 9074 adds a “UID” property to “VALARM” components to allow a unique identifier to be specified. The value of this property can then be used to refer uniquely to the “VALARM” component.

      This property can be specified once only.

    Security:

      RFC 7986 states that UID values MUST NOT include any data that might identify a user, host, domain, or any other security- or privacy-sensitive information. It is RECOMMENDED that calendar user agents now generate “UID” values that are hex-encoded random Universally Unique Identifier (UUID) values as defined in Sections 4.4 and 4.5 of RFC 4122. You can use the `uuid` module to generate new UUIDs.

    Compatibility:

      For Alarms, `X-ALARMUID` is also considered.

    Examples

    The following is an example of such a property value: `5FC53010-1267-4F8E-BC28-1D7AE55A7C99`.

    Set the UID of a calendar:

        >>> from icalendar import Calendar
        >>> from uuid import uuid4
        >>> calendar = Calendar()
        >>> calendar.uid = uuid4()
        >>> print(calendar.to_ical())
        BEGIN:VCALENDAR
        UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
        END:VCALENDAR

icalendar.cal.get_example(component_directory: str, example_name: str) → bytes

  Return an example and raise an error if it is absent.

## icalendar.caselessdict

class icalendar.caselessdict.CaselessDict(*args, **kwargs)

  A dictionary that isn’t case sensitive, and only uses strings as keys. Values retain their case.

  copy() → a shallow copy of od
  get(key, default=None)

    Return the value for key if key is in the dictionary, else default.

  pop(key[, default]) → v, remove specified key and return the corresponding value.

    If the key is not found, return the default if given; otherwise, raise a KeyError.

  popitem()

    Remove and return a (key, value) pair from the dictionary.

    Pairs are returned in LIFO order if last is true or FIFO order if false.

  setdefault(key, value=None)

    Insert key with a value of default if key is not in the dictionary.

    Return the value for key if key is in the dictionary, else default.

  sorted_items()

    Sorts items according to the canonical_order for the derived class. Items not specified in canonical_order will appear at the end.

  sorted_keys()

    Sorts keys according to the canonical_order for the derived class. Keys not specified in canonical_order will appear at the end.

  update([E, ]**F) → None. Update D from mapping/iterable E and F.

    If E is present and has a .keys() method, then does: for k in E.keys(): D[k] = E[k] If E is present and lacks a .keys() method, then does: for k, v in E: D[k] = v In either case, this is followed by: for k in F: D[k] = F[k]

icalendar.caselessdict.canonsort_items(dict1, canonical_order=None)

  Returns a list of items from dict1, sorted by canonical_order.

icalendar.caselessdict.canonsort_keys(keys, canonical_order=None)

  Sorts leading keys according to canonical_order. Keys not specified in canonical_order will appear alphabetically at the end.

## icalendar.cli

utility program that allows user to preview calendar’s events

icalendar.cli.view(event)

  Make a human readable summary of an iCalendar file.

  Returns str:

    Human readable summary.

## icalendar.enums

Enumerations for different types in the RFCs.

class icalendar.enums.CUTYPE(*values)

  Enum for CTYPE from RFC 5545.

  ``INDIVIDUAL``,
  ``GROUP``,
  ``RESOURCE``,
  ``ROOM``,
  ``UNKNOWN``

class icalendar.enums.FBTYPE(*values)

  Enum for FBTYPE from RFC 5545.

  ``FREE``,
  ``BUSY``,
  ``BUSY-UNAVAILABLE``,
  ``BUSY-TENTATIVE``

class icalendar.enums.PARTSTAT(*values)

  Enum for PARTSTAT from RFC 5545.

  ``NEEDS_ACTION``,
  ``ACCEPTED``,
  ``DECLINED``,
  ``TENTATIVE``,
  ``DELEGATED``,
  ``COMPLETED``,
  ``IN_PROCESS``

class icalendar.enums.RANGE(*values)

  Enum for RANGE from RFC 5545.

  ``THISANDFUTURE``,
  ``THISANDPRIOR``

class icalendar.enums.RELATED(*values)

  Enum for RELATED from RFC 5545.

  ``START``,
  ``END``

class icalendar.enums.RELTYPE(*values)

  Enum for RELTYPE from RFC 5545.

  ``PARENT``,
  ``CHILD``,
  ``SIBLING``

class icalendar.enums.ROLE(*values)

  Enum for ROLE from RFC 5545.

  ``CHAIR``,
  ``REQ-PARTICIPANT``,
  ``OPT-PARTICIPANT``,
  ``NON-PARTICIPANT``

## icalendar.error

Errors thrown by icalendar.

exception icalendar.error.ComponentEndMissing

  We are missing the end of a component that the alarm is for.

  Use Alarms.set_end().

exception icalendar.error.ComponentStartMissing

  We are missing the start of a component that the alarm is for.

  Use Alarms.set_start().

exception icalendar.error.FeatureWillBeRemovedInFutureVersion

  This feature will be removed in a future version.

exception icalendar.error.IncompleteAlarmInformation

  The alarms cannot be calculated yet because information is missing.

exception icalendar.error.IncompleteComponent

  The component is missing attributes.

  The attributes are not required, otherwise this would be an InvalidCalendar. But in order to perform calculations, this attribute is required.

  This error is not raised in the UPPERCASE properties like .DTSTART, only in the lowercase computations like .start.

exception icalendar.error.InvalidCalendar

  The calendar given is not valid.

  This calendar does not conform with RFC 5545 or breaks other RFCs.

exception icalendar.error.LocalTimezoneMissing

  We are missing the local timezone to compute the value.

  Use Alarms.set_local_timezone().

exception icalendar.error.WillBeRemovedInVersion7

  This feature will be removed in icalendar version 7.

  Suppress FeatureWillBeRemovedInFutureVersion instead.

## icalendar.param

Parameter access for icalendar.

Related:

- RFC 5545, Section 3.2. Property Parameters

- RFC 7986, Section 6. Property Parameters

- collective/icalendar#798

icalendar.param.quoted_list_parameter(name: str, doc: str) → property

  Return a parameter that contains a quoted list.

icalendar.param.string_parameter(name: str, doc: str, default: ~typing.Callable = <function _default_return_none>, convert: ~typing.Callable[[str], ~icalendar.param.T] | None = None, convert_to: ~typing.Callable[[~icalendar.param.T], str] | None = None) → property

  Return a parameter with a quoted value (case sensitive).

## icalendar.parser

This module parses and generates contentlines as defined in RFC 5545 (iCalendar), but will probably work for other MIME types with similar syntax. Eg. RFC 2426 (vCard)

It is stupid in the sense that it treats the content purely as strings. No type conversion is attempted.

class icalendar.parser.Contentline(value, strict=False, encoding='utf-8')

  A content line is basically a string that can be folded and parsed into parts.

  classmethod from_ical(ical, strict=False)

    Unfold the content lines in an iCalendar into long content lines.

  classmethod from_parts(name: str | bytes, params: Parameters, values, sorted=True)

    Turn a parts into a content line.

  parts()

    Split the content line up into (name, parameters, values) parts.

  to_ical()

    Long content lines are folded so they are less than 75 characters wide.

class icalendar.parser.Contentlines(iterable=(), /)

  I assume that iCalendar files generally are a few kilobytes in size. Then this should be efficient. for Huge files, an iterator should probably be used instead.

  classmethod from_ical(st)

    Parses a string into content lines.

  to_ical()

    Simply join self.

class icalendar.parser.Parameters(*args, **kwargs)

  Parser and generator of Property parameter strings. It knows nothing of datatypes. Its main concern is textual structure.

  classmethod from_ical(st, strict=False)

    Parses the parameter format from ical text format.

  params()

    In RFC 5545 keys are called parameters, so this is to be consitent with the naming conventions.

icalendar.parser.dquote(val, always_quote=False)

  Enclose parameter values containing [,;:] in double quotes.

icalendar.parser.escape_char(text)

  Format value according to iCalendar TEXT escaping rules.

icalendar.parser.foldline(line, limit=75, fold_sep='\r\n ')

  Make a string folded as defined in RFC5545 Lines of text SHOULD NOT be longer than 75 octets, excluding the line break. Long content lines SHOULD be split into a multiple line representations using a line “folding” technique. That is, a long line can be split between any two characters by inserting a CRLF immediately followed by a single linear white-space character (i.e., SPACE or HTAB).

icalendar.parser.param_value(value, always_quote=False)

  Returns a parameter value.

icalendar.parser.q_join(lst, sep=',', always_quote=False)

  Joins a list on sep, quoting strings with QUOTABLE chars.

icalendar.parser.q_split(st, sep=',', maxsplit=-1)

  Splits a string on char, taking double (q)uotes into considderation.

icalendar.parser.rfc_6868_escape(param_value: str) → str

  Take care of RFC 6868 escaping.

  - ^ -> ^^

  - “ -> ^’

  - newline -> ^n

icalendar.parser.rfc_6868_unescape(param_value: str) → str

  Take care of RFC 6868 unescaping.

  - ^^ -> ^

  - ^n -> system specific newline

  - ^’ -> “

  - ^ with others stay intact

## icalendar.parser_tools

icalendar.parser_tools.data_encode(data: str | bytes | dict | list, encoding='utf-8') → bytes | List[bytes] | dict

  Encode all datastructures to the given encoding. Currently unicode strings, dicts and lists are supported.

icalendar.parser_tools.from_unicode(value: str | bytes, encoding='utf-8') → bytes

  Converts a value to bytes, even if it already is bytes :param value: The value to convert :param encoding: The encoding to use in the conversion :return: The bytes representation of the value

icalendar.parser_tools.to_unicode(value: str | bytes, encoding='utf-8-sig') → str

  Converts a value to unicode, even if it is already a unicode string.

## icalendar.prop

This module contains the parser/generators (or coders/encoders if you prefer) for the classes/datatypes that are used in iCalendar:

# This module defines these property value data types and property parameters

4.2 Defined property parameters are:

    ALTREP, CN, CUTYPE, DELEGATED-FROM, DELEGATED-TO, DIR, ENCODING, FMTTYPE,
    FBTYPE, LANGUAGE, MEMBER, PARTSTAT, RANGE, RELATED, RELTYPE, ROLE, RSVP,
    SENT-BY, TZID, VALUE

4.3 Defined value data types are:

    BINARY, BOOLEAN, CAL-ADDRESS, DATE, DATE-TIME, DURATION, FLOAT, INTEGER,
    PERIOD, RECUR, TEXT, TIME, URI, UTC-OFFSET

iCalendar properties have values. The values are strongly typed. This module defines these types, calling val.to_ical() on them will render them as defined in rfc5545.

If you pass any of these classes a Python primitive, you will have an object that can render itself as iCalendar formatted date.

Property Value Data Types start with a ‘v’. they all have an to_ical() and from_ical() method. The to_ical() method generates a text string in the iCalendar format. The from_ical() method can parse this format and return a primitive Python datatype. So it should always be true that:

    x == vDataType.from_ical(VDataType(x).to_ical())

These types are mainly used for parsing and file generation. But you can set them directly.

class icalendar.prop.TimeBase

  Make classes with a datetime/date comparable.

  property RANGE: RANGE | str | None

    Specify the effective range of recurrence instances from the instance specified by the recurrence identifier specified by the property.

    Description:

      This parameter can be specified on a property that specifies a recurrence identifier. The parameter specifies the effective range of recurrence instances that is specified by the property. The effective range is from the recurrence identifier specified by the property. If this parameter is not specified on an allowed property, then the default range is the single instance specified by the recurrence identifier value of the property. The parameter value can only be “THISANDFUTURE” to indicate a range defined by the recurrence identifier and all subsequent instances. The value “THISANDPRIOR” is deprecated by this revision of iCalendar and MUST NOT be generated by applications.

  property RELATED: RELATED | str

    Specify the relationship of the alarm trigger with respect to the start or end of the calendar component.

    Description:

      This parameter can be specified on properties that specify an alarm trigger with a “DURATION” value type. The parameter specifies whether the alarm will trigger relative to the start or end of the calendar component. The parameter value START will set the alarm to trigger off the start of the calendar component; the parameter value END will set the alarm to trigger off the end of the calendar component. If the parameter is not specified on an allowable property, then the default is START.

  property TZID: str | None

    Specify the identifier for the time zone definition for a time component in the property value.

    Description:

      This parameter MUST be specified on the “DTSTART”, “DTEND”, “DUE”, “EXDATE”, and “RDATE” properties when either a DATE-TIME or TIME value type is specified and when the value is neither a UTC or a “floating” time. Refer to the DATE-TIME or TIME value type definition for a description of UTC and “floating time” formats. This property parameter specifies a text value that uniquely identifies the “VTIMEZONE” calendar component to be used when evaluating the time portion of the property. The value of the “TZID” property parameter will be equal to the value of the “TZID” property for the matching time zone definition. An individual “VTIMEZONE” calendar component MUST be specified for each unique “TZID” parameter value specified in the iCalendar object.

      The parameter MUST be specified on properties with a DATE-TIME value if the DATE-TIME is not either a UTC or a “floating” time. Failure to include and follow VTIMEZONE definitions in iCalendar objects may lead to inconsistent understanding of the local time at any given location.

      The presence of the SOLIDUS character as a prefix, indicates that this “TZID” represents a unique ID in a globally defined time zone registry (when such registry is defined).

    Note

    This document does not define a naming convention for time zone identifiers. Implementers may want to use the naming conventions defined in existing time zone specifications such as the public-domain TZ database (TZDB). The specification of globally unique time zone identifiers is not addressed by this document and is left for future study.

class icalendar.prop.TypesFactory(*args, **kwargs)

  All Value types defined in RFC 5545 are registered in this factory class.

  The value and parameter names don’t overlap. So one factory is enough for both kinds.

  for_property(name)

    Returns a the default type for a property or parameter

  from_ical(name, value)

    Decodes a named property or parameter value from an icalendar encoded string to a primitive python type.

  to_ical(name, value)

    Encodes a named value from a primitive python type to an icalendar encoded string.

icalendar.prop.tzid_from_dt(dt: datetime) → str | None

  Retrieve the timezone id from the datetime object.

icalendar.prop.tzid_from_tzinfo(tzinfo: tzinfo | None) → str | None

  Retrieve the timezone id from the tzinfo object.

  Some timezones are equivalent. Thus, we might return one ID that is equivelant to others.

class icalendar.prop.vBinary(obj)

  Binary property values are base 64 encoded.

class icalendar.prop.vBoolean(*args, params={}, **kwargs)

  Boolean

  Value Name: BOOLEAN

  Purpose: This value type is used to identify properties that contain

    either a “TRUE” or “FALSE” Boolean value.

  Format Definition: This value type is defined by the following

    notation:

      boolean    = "TRUE" / "FALSE"

  Description: These values are case-insensitive text. No additional

    content value encoding is defined for this value type.

  Example: The following is an example of a hypothetical property that

    has a BOOLEAN value type:

      TRUE

      >>> from icalendar.prop import vBoolean
      >>> boolean = vBoolean.from_ical('TRUE')
      >>> boolean
      True
      >>> boolean = vBoolean.from_ical('FALSE')
      >>> boolean
      False
      >>> boolean = vBoolean.from_ical('True')
      >>> boolean
      True

class icalendar.prop.vCalAddress(value, encoding='utf-8', params={})

  Calendar User Address

  Value Name:

    CAL-ADDRESS

  Purpose:

    This value type is used to identify properties that contain a calendar user address.

  Description:

    The value is a URI as defined by [RFC3986] or any other IANA-registered form for a URI. When used to address an Internet email transport address for a calendar user, the value MUST be a mailto URI, as defined by [RFC2368].

  Example

  `mailto:` is in front of the address.

      mailto:jane_doe@example.com

  Parsing:

      >>> from icalendar import vCalAddress
      >>> cal_address = vCalAddress.from_ical('mailto:jane_doe@example.com')
      >>> cal_address
      vCalAddress('mailto:jane_doe@example.com')

  Encoding:

      >>> from icalendar import vCalAddress, Event
      >>> event = Event()
      >>> jane = vCalAddress("mailto:jane_doe@example.com")
      >>> jane.name = "Jane"
      >>> event["organizer"] = jane
      >>> print(event.to_ical())
      BEGIN:VEVENT
      ORGANIZER;CN=Jane:mailto:jane_doe@example.com
      END:VEVENT

  property CN: str

    Specify the common name to be associated with the calendar user specified.

    Description:

      This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the common name to be associated with the calendar user specified by the property. The parameter value is text. The parameter value can be used for display text to be associated with the calendar address specified by the property.

  property CUTYPE: CUTYPE | str

    Identify the type of calendar user specified by the property.

    Description:

      This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter identifies the type of calendar user specified by the property. If not specified on a property that allows this parameter, the default is INDIVIDUAL. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the UNKNOWN value.

  property DELEGATED_FROM: tuple[str]

    Specify the calendar users that have delegated their participation to the calendar user specified by the property.

    Description:

      This parameter can be specified on properties with a CAL-ADDRESS value type. This parameter specifies those calendar users that have delegated their participation in a group-scheduled event or to-do to the calendar user specified by the property. The individual calendar address parameter values MUST each be specified in a quoted-string.

  property DELEGATED_TO: tuple[str]

    Specify the calendar users to whom the calendar user specified by the property has delegated participation.

    Description:

      This parameter can be specified on properties with a CAL-ADDRESS value type. This parameter specifies those calendar users whom have been delegated participation in a group-scheduled event or to-do by the calendar user specified by the property. The individual calendar address parameter values MUST each be specified in a quoted-string.

  property DIR: str | None

    Specify reference to a directory entry associated with the calendar user specified by the property.

    Description:

      This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies a reference to the directory entry associated with the calendar user specified by the property. The parameter value is a URI. The URI parameter value MUST be specified in a quoted-string.

    Note

    While there is no restriction imposed on the URI schemes allowed for this parameter, CID RFC 2392, DATA RFC 2397, FILE RFC 1738, FTP RFC 1738, HTTP RFC 2616, HTTPS RFC 2818, LDAP RFC 4516, and MID RFC 2392 are the URI schemes most commonly used by current implementations.

  property LANGUAGE: str | None

    Specify the language for text values in a property or property parameter.

    Description:

      This parameter identifies the language of the text in the property value and of all property parameter values of the property. The value of the “LANGUAGE” property parameter is that defined in RFC 5646.

      For transport in a MIME entity, the Content-Language header field can be used to set the default language for the entire body part. Otherwise, no default language is assumed.

  property PARTSTAT: PARTSTAT | str

    Specify the participation status for the calendar user specified by the property.

    Description:

      This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter identifies the participation status for the calendar user specified by the property value. The parameter values differ depending on whether they are associated with a group-scheduled “VEVENT”, “VTODO”, or “VJOURNAL”. The values MUST match one of the values allowed for the given calendar component. If not specified on a property that allows this parameter, the default value is NEEDS-ACTION. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the NEEDS-ACTION value.

  property ROLE: ROLE | str

    Specify the participation role for the calendar user specified by the property.

    Description:

      This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the participation role for the calendar user specified by the property in the group schedule calendar component. If not specified on a property that allows this parameter, the default value is REQ-PARTICIPANT. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the REQ-PARTICIPANT value.

  property RSVP: bool

    Specify whether there is an expectation of a favor of anreply from the calendar user specified by the property value.

    Description:

      This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter identifies the expectation of a reply from the calendar user specified by the property value. This parameter is used by the “Organizer” to request a participation status reply from an “Attendee” of a group-scheduled event or to-do. If not specified on a property that allows this parameter, the default value is `False`.

  property SENT_BY: str | None

    Specify the calendar user that is acting on behalf of the calendar user specified by the property.

    Description:

      This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the calendar user that is acting on behalf of the calendar user specified by the property. The parameter value MUST be a mailto URI as defined in RFC 2368. The individual calendar address parameter values MUST each be specified in a quoted-string.

  property email: str

    at the start.

    Type:

      The email address without mailto

  property name: str

    Specify the common name to be associated with the calendar user specified.

    Description:

      This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the common name to be associated with the calendar user specified by the property. The parameter value is text. The parameter value can be used for display text to be associated with the calendar address specified by the property.

class icalendar.prop.vDDDLists(dt_list)

  A list of vDDDTypes values.

class icalendar.prop.vDDDTypes(dt)

  A combined Datetime, Date or Duration parser/generator. Their format cannot be confused, and often values can be of either types. So this is practical.

class icalendar.prop.vDate(dt)

  Date

  Value Name:

    DATE

  Purpose:

    This value type is used to identify values that contain a calendar date.

  Format Definition:

    This value type is defined by the following notation:

        date               = date-value

        date-value         = date-fullyear date-month date-mday
        date-fullyear      = 4DIGIT
        date-month         = 2DIGIT        ;01-12
        date-mday          = 2DIGIT        ;01-28, 01-29, 01-30, 01-31
                                           ;based on month/year

  Description:

    If the property permits, multiple “date” values are specified as a COMMA-separated list of values. The format for the value type is based on the [ISO.8601.2004] complete representation, basic format for a calendar date. The textual format specifies a four-digit year, two-digit month, and two-digit day of the month. There are no separator characters between the year, month, and day component text.

  Example

  The following represents July 14, 1997:

      19970714

      >>> from icalendar.prop import vDate
      >>> date = vDate.from_ical('19970714')
      >>> date.year
      1997
      >>> date.month
      7
      >>> date.day
      14

class icalendar.prop.vDatetime(dt, params={})

  Render and generates icalendar datetime format.

  vDatetime is timezone aware and uses a timezone library. When a vDatetime object is created from an ical string, you can pass a valid timezone identifier. When a vDatetime object is created from a python datetime object, it uses the tzinfo component, if present. Otherwise a timezone-naive object is created. Be aware that there are certain limitations with timezone naive DATE-TIME components in the icalendar standard.

  static from_ical(ical, timezone=None)

    Create a datetime from the RFC string.

    Format:

        YYYYMMDDTHHMMSS

        >>> from icalendar import vDatetime
        >>> vDatetime.from_ical("20210302T101500")
        datetime.datetime(2021, 3, 2, 10, 15)

        >>> vDatetime.from_ical("20210302T101500", "America/New_York")
        datetime.datetime(2021, 3, 2, 10, 15, tzinfo=ZoneInfo(key='America/New_York'))

        >>> from zoneinfo import ZoneInfo
        >>> timezone = ZoneInfo("Europe/Berlin")
        >>> vDatetime.from_ical("20210302T101500", timezone)
        datetime.datetime(2021, 3, 2, 10, 15, tzinfo=ZoneInfo(key='Europe/Berlin'))

class icalendar.prop.vDuration(td, params={})

  Duration

  Value Name:

    DURATION

  Purpose:

    This value type is used to identify properties that contain a duration of time.

  Format Definition:

    This value type is defined by the following notation:

        dur-value  = (["+"] / "-") "P" (dur-date / dur-time / dur-week)

        dur-date   = dur-day [dur-time]
        dur-time   = "T" (dur-hour / dur-minute / dur-second)
        dur-week   = 1*DIGIT "W"
        dur-hour   = 1*DIGIT "H" [dur-minute]
        dur-minute = 1*DIGIT "M" [dur-second]
        dur-second = 1*DIGIT "S"
        dur-day    = 1*DIGIT "D"

  Description:

    If the property permits, multiple “duration” values are specified by a COMMA-separated list of values. The format is based on the [ISO.8601.2004] complete representation basic format with designators for the duration of time. The format can represent nominal durations (weeks and days) and accurate durations (hours, minutes, and seconds). Note that unlike [ISO.8601.2004], this value type doesn’t support the “Y” and “M” designators to specify durations in terms of years and months. The duration of a week or a day depends on its position in the calendar. In the case of discontinuities in the time scale, such as the change from standard time to daylight time and back, the computation of the exact duration requires the subtraction or addition of the change of duration of the discontinuity. Leap seconds MUST NOT be considered when computing an exact duration. When computing an exact duration, the greatest order time components MUST be added first, that is, the number of days MUST be added first, followed by the number of hours, number of minutes, and number of seconds.

  Example

  A duration of 15 days, 5 hours, and 20 seconds would be:

      P15DT5H0M20S

  A duration of 7 weeks would be:

      P7W

      >>> from icalendar.prop import vDuration
      >>> duration = vDuration.from_ical('P15DT5H0M20S')
      >>> duration
      datetime.timedelta(days=15, seconds=18020)
      >>> duration = vDuration.from_ical('P7W')
      >>> duration
      datetime.timedelta(days=49)

  property dt: timedelta

    The time delta for compatibility.

class icalendar.prop.vFloat(*args, params={}, **kwargs)

  Float

  Value Name:

    FLOAT

  Purpose:

    This value type is used to identify properties that contain a real-number value.

  Format Definition:

    This value type is defined by the following notation:

        float      = (["+"] / "-") 1*DIGIT ["." 1*DIGIT]

  Description:

    If the property permits, multiple “float” values are specified by a COMMA-separated list of values.

    Example:

        1000000.0000001
        1.333
        -3.14

        >>> from icalendar.prop import vFloat
        >>> float = vFloat.from_ical('1000000.0000001')
        >>> float
        1000000.0000001
        >>> float = vFloat.from_ical('1.333')
        >>> float
        1.333
        >>> float = vFloat.from_ical('+1.333')
        >>> float
        1.333
        >>> float = vFloat.from_ical('-3.14')
        >>> float
        -3.14

class icalendar.prop.vFrequency(value, encoding='utf-8', params={})

  A simple class that catches illegal values.

class icalendar.prop.vGeo(geo: tuple[float | str | int, float | str | int], params={})

  Geographic Position

  Property Name:

    GEO

  Purpose:

    This property specifies information related to the global position for the activity specified by a calendar component.

  Value Type:

    FLOAT. The value MUST be two SEMICOLON-separated FLOAT values.

  Property Parameters:

    IANA and non-standard property parameters can be specified on this property.

  Conformance:

    This property can be specified in “VEVENT” or “VTODO” calendar components.

  Description:

    This property value specifies latitude and longitude, in that order (i.e., “LAT LON” ordering). The longitude represents the location east or west of the prime meridian as a positive or negative real number, respectively. The longitude and latitude values MAY be specified up to six decimal places, which will allow for accuracy to within one meter of geographical position. Receiving applications MUST accept values of this precision and MAY truncate values of greater precision.

    Example:

        GEO:37.386013;-122.082932

    Parse vGeo:

        >>> from icalendar.prop import vGeo
        >>> geo = vGeo.from_ical('37.386013;-122.082932')
        >>> geo
        (37.386013, -122.082932)

    Add a geo location to an event:

        >>> from icalendar import Event
        >>> event = Event()
        >>> latitude = 37.386013
        >>> longitude = -122.082932
        >>> event.add('GEO', (latitude, longitude))
        >>> event['GEO']
        vGeo((37.386013, -122.082932))

class icalendar.prop.vInline(value, encoding='utf-8', params={})

  This is an especially dumb class that just holds raw unparsed text and has parameters. Conversion of inline values are handled by the Component class, so no further processing is needed.

class icalendar.prop.vInt(*args, params={}, **kwargs)

  Integer

  Value Name:

    INTEGER

  Purpose:

    This value type is used to identify properties that contain a signed integer value.

  Format Definition:

    This value type is defined by the following notation:

        integer    = (["+"] / "-") 1*DIGIT

  Description:

    If the property permits, multiple “integer” values are specified by a COMMA-separated list of values. The valid range for “integer” is -2147483648 to 2147483647. If the sign is not specified, then the value is assumed to be positive.

    Example:

        1234567890
        -1234567890
        +1234567890
        432109876

        >>> from icalendar.prop import vInt
        >>> integer = vInt.from_ical('1234567890')
        >>> integer
        1234567890
        >>> integer = vInt.from_ical('-1234567890')
        >>> integer
        -1234567890
        >>> integer = vInt.from_ical('+1234567890')
        >>> integer
        1234567890
        >>> integer = vInt.from_ical('432109876')
        >>> integer
        432109876

class icalendar.prop.vMonth(month: str | int, params={})

  The number of the month for recurrence.

  In RFC 5545, this is just an int. In RFC 7529, this can be followed by L to indicate a leap month.

      >>> from icalendar import vMonth
      >>> vMonth(1) # first month January
      vMonth('1')
      >>> vMonth("5L") # leap month in Hebrew calendar
      vMonth('5L')
      >>> vMonth(1).leap
      False
      >>> vMonth("5L").leap
      True

  Definition from RFC:

      type-bymonth = element bymonth {
         xsd:positiveInteger |
         xsd:string
      }

  property leap: bool

    Whether this is a leap month.

  to_ical() → bytes

    The ical representation.

class icalendar.prop.vPeriod(per: tuple[datetime, datetime | timedelta])

  Period of Time

  Value Name:

    PERIOD

  Purpose:

    This value type is used to identify values that contain a precise period of time.

  Format Definition:

    This value type is defined by the following notation:

         period     = period-explicit / period-start

        period-explicit = date-time "/" date-time
        ; [ISO.8601.2004] complete representation basic format for a
        ; period of time consisting of a start and end.  The start MUST
        ; be before the end.

        period-start = date-time "/" dur-value
        ; [ISO.8601.2004] complete representation basic format for a
        ; period of time consisting of a start and positive duration
        ; of time.

  Description:

    If the property permits, multiple “period” values are specified by a COMMA-separated list of values. There are two forms of a period of time. First, a period of time is identified by its start and its end. This format is based on the [ISO.8601.2004] complete representation, basic format for “DATE- TIME” start of the period, followed by a SOLIDUS character followed by the “DATE-TIME” of the end of the period. The start of the period MUST be before the end of the period. Second, a period of time can also be defined by a start and a positive duration of time. The format is based on the [ISO.8601.2004] complete representation, basic format for the “DATE-TIME” start of the period, followed by a SOLIDUS character, followed by the [ISO.8601.2004] basic format for “DURATION” of the period.

  Example

  The period starting at 18:00:00 UTC, on January 1, 1997 and ending at 07:00:00 UTC on January 2, 1997 would be:

      19970101T180000Z/19970102T070000Z

  The period start at 18:00:00 on January 1, 1997 and lasting 5 hours and 30 minutes would be:

      19970101T180000Z/PT5H30M

      >>> from icalendar.prop import vPeriod
      >>> period = vPeriod.from_ical('19970101T180000Z/19970102T070000Z')
      >>> period = vPeriod.from_ical('19970101T180000Z/PT5H30M')

  property FBTYPE: FBTYPE | str

    Specify the free or busy time type.

    Description:

      This parameter specifies the free or busy time type. The value FREE indicates that the time interval is free for scheduling. The value BUSY indicates that the time interval is busy because one or more events have been scheduled for that interval. The value BUSY-UNAVAILABLE indicates that the time interval is busy and that the interval can not be scheduled. The value BUSY-TENTATIVE indicates that the time interval is busy because one or more events have been tentatively scheduled for that interval. If not specified on a property that allows this parameter, the default is BUSY. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the BUSY value.

  property dt

    Make this cooperate with the other vDDDTypes.

class icalendar.prop.vRecur(*args, params={}, **kwargs)

  Recurrence definition.

  Property Name:

    RRULE

  Purpose:

    This property defines a rule or repeating pattern for recurring events, to-dos, journal entries, or time zone definitions.

  Value Type:

    RECUR

  Property Parameters:

    IANA and non-standard property parameters can be specified on this property.

  Conformance:

    This property can be specified in recurring “VEVENT”, “VTODO”, and “VJOURNAL” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components of the “VTIMEZONE” calendar component, but it SHOULD NOT be specified more than once. The recurrence set generated with multiple “RRULE” properties is undefined.

  Description:

    The recurrence rule, if specified, is used in computing the recurrence set. The recurrence set is the complete set of recurrence instances for a calendar component. The recurrence set is generated by considering the initial “DTSTART” property along with the “RRULE”, “RDATE”, and “EXDATE” properties contained within the recurring component. The “DTSTART” property defines the first instance in the recurrence set. The “DTSTART” property value SHOULD be synchronized with the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value not synchronized with the recurrence rule is undefined. The final recurrence set is generated by gathering all of the start DATE-TIME values generated by any of the specified “RRULE” and “RDATE” properties, and then excluding any start DATE-TIME values specified by “EXDATE” properties. This implies that start DATE- TIME values specified by “EXDATE” properties take precedence over those specified by inclusion properties (i.e., “RDATE” and “RRULE”). Where duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

    The “DTSTART” property specified within the iCalendar object defines the first instance of the recurrence. In most cases, a “DTSTART” property of DATE-TIME value type used with a recurrence rule, should be specified as a date with local time and time zone reference to make sure all the recurrence instances start at the same local time regardless of time zone changes.

    If the duration of the recurring component is specified with the “DTEND” or “DUE” property, then the same exact duration will apply to all the members of the generated recurrence set. Else, if the duration of the recurring component is specified with the “DURATION” property, then the same nominal duration will apply to all the members of the generated recurrence set and the exact duration of each recurrence instance will depend on its specific start time. For example, recurrence instances of a nominal duration of one day will have an exact duration of more or less than 24 hours on a day where a time zone shift occurs. The duration of a specific recurrence may be modified in an exception component or simply by using an “RDATE” property of PERIOD value type.

  Examples

  The following RRULE specifies daily events for 10 occurrences.

      RRULE:FREQ=DAILY;COUNT=10

  Below, we parse the RRULE ical string.

      >>> from icalendar.prop import vRecur
      >>> rrule = vRecur.from_ical('FREQ=DAILY;COUNT=10')
      >>> rrule
      vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})

  You can choose to add an rrule to an `icalendar.cal.Event` or `icalendar.cal.Todo`.

      >>> from icalendar import Event
      >>> event = Event()
      >>> event.add('RRULE', 'FREQ=DAILY;COUNT=10')
      >>> event.rrules
      [vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]

class icalendar.prop.vSkip(*values)

  Skip values for RRULE.

  These are defined in RFC 7529.

  OMIT is the default value.

  Examples:

      >>> from icalendar import vSkip
      >>> vSkip.OMIT
      vSkip('OMIT')
      >>> vSkip.FORWARD
      vSkip('FORWARD')
      >>> vSkip.BACKWARD
      vSkip('BACKWARD')

class icalendar.prop.vText(value, encoding='utf-8', params={})

  Simple text.

  property ALTREP: str | None

    ALTREP - Specify an alternate text representation for the property value.

    Description:

      This parameter specifies a URI that points to an alternate representation for a textual property value. A property specifying this parameter MUST also include a value that reflects the default representation of the text value. The URI parameter value MUST be specified in a quoted-string.

    Note

    While there is no restriction imposed on the URI schemes allowed for this parameter, Content Identifier (CID) RFC 2392, HTTP RFC 2616, and HTTPS RFC 2818 are the URI schemes most commonly used by current implementations.

  property LANGUAGE: str | None

    Specify the language for text values in a property or property parameter.

    Description:

      This parameter identifies the language of the text in the property value and of all property parameter values of the property. The value of the “LANGUAGE” property parameter is that defined in RFC 5646.

      For transport in a MIME entity, the Content-Language header field can be used to set the default language for the entire body part. Otherwise, no default language is assumed.

  property RELTYPE: RELTYPE

    Specify the type of hierarchical relationship associated with the calendar component specified by the property.

    Description:

      This parameter can be specified on a property that references another related calendar. The parameter specifies the hierarchical relationship type of the calendar component referenced by the property. The parameter value can be PARENT, to indicate that the referenced calendar component is a superior of calendar component; CHILD to indicate that the referenced calendar component is a subordinate of the calendar component; or SIBLING to indicate that the referenced calendar component is a peer of the calendar component. If this parameter is not specified on an allowable property, the default relationship type is PARENT. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the PARENT value.

class icalendar.prop.vTime(*args)

  Time

  Value Name:

    TIME

  Purpose:

    This value type is used to identify values that contain a time of day.

  Format Definition:

    This value type is defined by the following notation:

        time         = time-hour time-minute time-second [time-utc]

        time-hour    = 2DIGIT        ;00-23
        time-minute  = 2DIGIT        ;00-59
        time-second  = 2DIGIT        ;00-60
        ;The "60" value is used to account for positive "leap" seconds.

        time-utc     = "Z"

  Description:

    If the property permits, multiple “time” values are specified by a COMMA-separated list of values. No additional content value encoding (i.e., BACKSLASH character encoding, see vText) is defined for this value type.

    The “TIME” value type is used to identify values that contain a time of day. The format is based on the [ISO.8601.2004] complete representation, basic format for a time of day. The text format consists of a two-digit, 24-hour of the day (i.e., values 00-23), two-digit minute in the hour (i.e., values 00-59), and two-digit seconds in the minute (i.e., values 00-60). The seconds value of 60 MUST only be used to account for positive “leap” seconds. Fractions of a second are not supported by this format.

    In parallel to the “DATE-TIME” definition above, the “TIME” value type expresses time values in three forms:

    The form of time with UTC offset MUST NOT be used. For example, the following is not valid for a time value:

        230000-0800        ;Invalid time format

    FORM #1 LOCAL TIME

    The local time form is simply a time value that does not contain the UTC designator nor does it reference a time zone. For example, 11:00 PM:

        230000

    Time values of this type are said to be “floating” and are not bound to any time zone in particular. They are used to represent the same hour, minute, and second value regardless of which time zone is currently being observed. For example, an event can be defined that indicates that an individual will be busy from 11:00 AM to 1:00 PM every day, no matter which time zone the person is in. In these cases, a local time can be specified. The recipient of an iCalendar object with a property value consisting of a local time, without any relative time zone information, SHOULD interpret the value as being fixed to whatever time zone the “ATTENDEE” is in at any given moment. This means that two “Attendees”, may participate in the same event at different UTC times; floating time SHOULD only be used where that is reasonable behavior.

    In most cases, a fixed time is desired. To properly communicate a fixed time in a property value, either UTC time or local time with time zone reference MUST be specified.

    The use of local time in a TIME value without the “TZID” property parameter is to be interpreted as floating time, regardless of the existence of “VTIMEZONE” calendar components in the iCalendar object.

    FORM #2: UTC TIME

    UTC time, or absolute time, is identified by a LATIN CAPITAL LETTER Z suffix character, the UTC designator, appended to the time value. For example, the following represents 07:00 AM UTC:

        070000Z

    The “TZID” property parameter MUST NOT be applied to TIME properties whose time values are specified in UTC.

    FORM #3: LOCAL TIME AND TIME ZONE REFERENCE

    The local time with reference to time zone information form is identified by the use the “TZID” property parameter to reference the appropriate time zone definition.

    Example:

      The following represents 8:30 AM in New York in winter, five hours behind UTC, in each of the three formats:

        083000
        133000Z
        TZID=America/New_York:083000

class icalendar.prop.vUTCOffset(td, params={})

  UTC Offset

  Value Name:

    UTC-OFFSET

  Purpose:

    This value type is used to identify properties that contain an offset from UTC to local time.

  Format Definition:

    This value type is defined by the following notation:

        utc-offset = time-numzone

        time-numzone = ("+" / "-") time-hour time-minute [time-second]

  Description:

    The PLUS SIGN character MUST be specified for positive UTC offsets (i.e., ahead of UTC). The HYPHEN-MINUS character MUST be specified for negative UTC offsets (i.e., behind of UTC). The value of “-0000” and “-000000” are not allowed. The time-second, if present, MUST NOT be 60; if absent, it defaults to zero.

    Example:

      The following UTC offsets are given for standard time for New York (five hours behind UTC) and Geneva (one hour ahead of UTC):

        -0500

        +0100

        >>> from icalendar.prop import vUTCOffset
        >>> utc_offset = vUTCOffset.from_ical('-0500')
        >>> utc_offset
        datetime.timedelta(days=-1, seconds=68400)
        >>> utc_offset = vUTCOffset.from_ical('+0100')
        >>> utc_offset
        datetime.timedelta(seconds=3600)

class icalendar.prop.vUri(value, encoding='utf-8', params={})

  URI

  Value Name:

    URI

  Purpose:

    This value type is used to identify values that contain a uniform resource identifier (URI) type of reference to the property value.

  Format Definition:

    This value type is defined by the following notation:

        uri = scheme ":" hier-part [ "?" query ] [ "#" fragment ]

  Description:

    This value type might be used to reference binary information, for values that are large, or otherwise undesirable to include directly in the iCalendar object.

    Property values with this value type MUST follow the generic URI syntax defined in [RFC3986].

    When a property parameter value is a URI value type, the URI MUST be specified as a quoted-string value.

    Example:

      The following is a URI for a network file:

          http://example.com/my-report.txt

          >>> from icalendar.prop import vUri
          >>> uri = vUri.from_ical('http://example.com/my-report.txt')
          >>> uri
          'http://example.com/my-report.txt'

class icalendar.prop.vWeekday(value, encoding='utf-8', params={})

  Either a `weekday` or a `weekdaynum`

      >>> from icalendar import vWeekday
      >>> vWeekday("MO") # Simple weekday
      'MO'
      >>> vWeekday("2FR").relative # Second friday
      2
      >>> vWeekday("2FR").weekday
      'FR'
      >>> vWeekday("-1SU").relative # Last Sunday
      -1

  Definition from RFC 5545, Section 3.3.10:

      weekdaynum = [[plus / minus] ordwk] weekday
      plus        = "+"
      minus       = "-"
      ordwk       = 1*2DIGIT       ;1 to 53
      weekday     = "SU" / "MO" / "TU" / "WE" / "TH" / "FR" / "SA"
      ;Corresponding to SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY,
      ;FRIDAY, and SATURDAY days of the week.

## icalendar.tools

Utility functions for icalendar.

class icalendar.tools.UIDGenerator

  Use this only if you’re too lazy to create real UUIDs.

  Deprecated since version 6.2.1: Use the Python standard library’s `uuid.uuid4()` instead.

  static rnd_string(length=16) → str

    Generates a string with random characters of length.

    Deprecated since version 6.2.1: Use the Python standard library’s `uuid.uuid4()` instead.

  static uid(host_name='example.com', unique='')

    Generates a unique ID consisting of `datetime-uniquevalue@host`.

    For example:

    >     20050105T225746Z-HKtJMqUgdO0jDUwm@example.com

    Deprecated since version 6.2.1: Use the Python standard library’s `uuid.uuid5()` instead.

icalendar.tools.is_date(dt: date) → bool

  Whether this is a date and not a datetime.

icalendar.tools.is_datetime(dt: date) → bool

  Whether this is a date and not a datetime.

icalendar.tools.is_pytz(tz: tzinfo)

  Whether the timezone requires localize() and normalize().

icalendar.tools.is_pytz_dt(dt: date)

  Whether the time requires localize() and normalize().

icalendar.tools.normalize_pytz(dt: date)

  We have to normalize the time after a calculation if we use pytz.

  pytz requires this function to be used in order to correctly calculate the timezone’s offset after calculations.

icalendar.tools.to_datetime(dt: date) → datetime

  Make sure we have a datetime, not a date.

## icalendar.timezone

This package contains all functionality for timezones.

class icalendar.timezone.TZP(provider: str | TZProvider = 'zoneinfo')

  This is the timezone provider proxy.

  If you would like to have another timezone implementation, you can create a new one and pass it to this proxy. All of icalendar will then use this timezone implementation.

  cache_timezone_component(timezone_component: cal.Timezone) → None

    Cache the timezone that is created from a timezone component if it is not already known.

    This can influence the result from timezone(): Once cached, the custom timezone is returned from timezone().

  clean_timezone_id(tzid: str) → str

    Return a clean version of the timezone id.

    Timezone ids can be a bit unclean, starting with a / for example. Internally, we should use this to identify timezones.

  create_timezone(timezone_component: cal.Timezone) → datetime.tzinfo

    Create a timezone from a timezone component.

    This component will not be cached.

  fix_rrule_until(rrule: rrule, ical_rrule: prop.vRecur) → None

    Make sure the until value works.

  localize(dt: datetime.date, tz: datetime.tzinfo | str | None) → datetime.datetime

    Localize a datetime to a timezone.

  localize_utc(dt: datetime.date) → datetime.datetime

    Return the datetime in UTC.

    If the datetime has no timezone, set UTC as its timezone.

  property name: str

    The name of the timezone component used.

  timezone(tz_id: str) → datetime.tzinfo | None

    Return a timezone with an id or None if we cannot find it.

  use(provider: str | TZProvider)

    Switch to a different timezone provider.

  use_default()

    Use the default timezone provider.

  use_pytz() → None

    Use pytz as the timezone provider.

  use_zoneinfo() → None

    Use zoneinfo as the timezone provider.

  uses_pytz() → bool

    Whether we use pytz at all.

  uses_zoneinfo() → bool

    Whether we use zoneinfo.

icalendar.timezone.tzid_from_dt(dt: datetime) → str | None

  Retrieve the timezone id from the datetime object.

icalendar.timezone.tzid_from_tzinfo(tzinfo: tzinfo | None) → str | None

  Retrieve the timezone id from the tzinfo object.

  Some timezones are equivalent. Thus, we might return one ID that is equivelant to others.

icalendar.timezone.tzids_from_tzinfo(tzinfo: tzinfo | None) → tuple[str]

  Get several timezone ids if we can identify the timezone.

      >>> import zoneinfo
      >>> from icalendar.timezone.tzid import tzids_from_tzinfo
      >>> tzids_from_tzinfo(zoneinfo.ZoneInfo("Arctic/Longyearbyen"))
      ('Arctic/Longyearbyen', 'Atlantic/Jan_Mayen', 'Europe/Berlin', 'Europe/Budapest', 'Europe/Copenhagen', 'Europe/Oslo', 'Europe/Stockholm', 'Europe/Vienna')
      >>> from dateutil.tz import gettz
      >>> tzids_from_tzinfo(gettz("Europe/Berlin"))
      ('Europe/Berlin', 'Arctic/Longyearbyen', 'Atlantic/Jan_Mayen', 'Europe/Budapest', 'Europe/Copenhagen', 'Europe/Oslo', 'Europe/Stockholm', 'Europe/Vienna')

icalendar.timezone.use_pytz()

  Use pytz as the implementation that looks up and creates timezones.

icalendar.timezone.use_zoneinfo()

  Use zoneinfo as the implementation that looks up and creates timezones.

This module identifies timezones.

Normally, timezones have ids. This is a way to access the ids if you have a datetime.tzinfo object.

icalendar.timezone.tzid.tzid_from_dt(dt: datetime) → str | None

  Retrieve the timezone id from the datetime object.

icalendar.timezone.tzid.tzid_from_tzinfo(tzinfo: tzinfo | None) → str | None

  Retrieve the timezone id from the tzinfo object.

  Some timezones are equivalent. Thus, we might return one ID that is equivelant to others.

icalendar.timezone.tzid.tzids_from_tzinfo(tzinfo: tzinfo | None) → tuple[str]

  Get several timezone ids if we can identify the timezone.

      >>> import zoneinfo
      >>> from icalendar.timezone.tzid import tzids_from_tzinfo
      >>> tzids_from_tzinfo(zoneinfo.ZoneInfo("Arctic/Longyearbyen"))
      ('Arctic/Longyearbyen', 'Atlantic/Jan_Mayen', 'Europe/Berlin', 'Europe/Budapest', 'Europe/Copenhagen', 'Europe/Oslo', 'Europe/Stockholm', 'Europe/Vienna')
      >>> from dateutil.tz import gettz
      >>> tzids_from_tzinfo(gettz("Europe/Berlin"))
      ('Europe/Berlin', 'Arctic/Longyearbyen', 'Atlantic/Jan_Mayen', 'Europe/Budapest', 'Europe/Copenhagen', 'Europe/Oslo', 'Europe/Stockholm', 'Europe/Vienna')

class icalendar.timezone.tzp.TZP(provider: str | TZProvider = 'zoneinfo')

  This is the timezone provider proxy.

  If you would like to have another timezone implementation, you can create a new one and pass it to this proxy. All of icalendar will then use this timezone implementation.

  cache_timezone_component(timezone_component: cal.Timezone) → None

    Cache the timezone that is created from a timezone component if it is not already known.

    This can influence the result from timezone(): Once cached, the custom timezone is returned from timezone().

  clean_timezone_id(tzid: str) → str

    Return a clean version of the timezone id.

    Timezone ids can be a bit unclean, starting with a / for example. Internally, we should use this to identify timezones.

  create_timezone(timezone_component: cal.Timezone) → datetime.tzinfo

    Create a timezone from a timezone component.

    This component will not be cached.

  fix_rrule_until(rrule: rrule, ical_rrule: prop.vRecur) → None

    Make sure the until value works.

  localize(dt: datetime.date, tz: datetime.tzinfo | str | None) → datetime.datetime

    Localize a datetime to a timezone.

  localize_utc(dt: datetime.date) → datetime.datetime

    Return the datetime in UTC.

    If the datetime has no timezone, set UTC as its timezone.

  property name: str

    The name of the timezone component used.

  timezone(tz_id: str) → datetime.tzinfo | None

    Return a timezone with an id or None if we cannot find it.

  use(provider: str | TZProvider)

    Switch to a different timezone provider.

  use_default()

    Use the default timezone provider.

  use_pytz() → None

    Use pytz as the timezone provider.

  use_zoneinfo() → None

    Use zoneinfo as the timezone provider.

  uses_pytz() → bool

    Whether we use pytz at all.

  uses_zoneinfo() → bool

    Whether we use zoneinfo.

## icalendar.version

Version file as a stable interface for the generated _version.py file.