icalendar.cal.todo module#

class icalendar.cal.todo.Todo(*args, **kwargs)[source]#

Bases: Component

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".

Examples

Create a new Todo:

>>> from icalendar import Todo
>>> todo = Todo.new()
>>> print(todo.to_ical())
BEGIN:VTODO
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
END:VTODO

Complete the example Todo.

>>> from datetime import datetime, timezone
>>> from icalendar import Todo, STATUS
>>> todo = Todo.example()
>>> todo["PERCENT-COMPLETE"] = 100
>>> todo["COMPLETED"] = datetime(2007, 5, 1, 12, tzinfo=timezone.utc)
>>> todo.status = STATUS.COMPLETED
>>> print(todo.to_ical().decode())
BEGIN:VTODO
CATEGORIES:FAMILY,FINANCE
CLASS:CONFIDENTIAL
COMPLETED:2007-05-01 12:00:00+00:00
DTSTAMP:20070313T123432Z
DUE;VALUE=DATE:20070501
PERCENT-COMPLETE:100
STATUS:COMPLETED
SUMMARY:Submit Quebec Income Tax Return for 2006
UID:20070313T123432Z-456553@example.com
END:VTODO

Set keys to upper for initial dict.

property CREATED: datetime | None#

The CREATED property. datetime in UTC

All values will be converted to a datetime in UTC.

CREATED specifies the date and time that the calendar information was created by the calendar user agent in the calendar store.

Conformance:
The property can be specified once in "VEVENT", "VTODO", or "VJOURNAL" calendar components. The value MUST be specified as a date with UTC time.

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 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 VTODO. 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 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.

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.

add(name, value, parameters=None, encode=True)#

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)#: Add a subcomponent to this component.

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 attendees: list[vCalAddress]#

ATTENDEE defines one or more "Attendees" within a calendar component.

Conformance:: This property MUST be specified in an iCalendar object that specifies a group-scheduled calendar entity. This property MUST NOT be specified in an iCalendar object when publishing the calendar information (e.g., NOT in an iCalendar object that specifies the publication of a calendar user's busy time, event, to-do, or journal). This property is not specified in an iCalendar object that specifies only a time zone definition or that defines calendar components that are not group-scheduled components, but are components only on a single user's calendar.
Description:: This property MUST only be specified within calendar components to specify participants, non-participants, and the chair of a group-scheduled calendar entity. The property is specified within an "EMAIL" category of the "VALARM" calendar component to specify an email address that is to receive the email type of iCalendar alarm.

Examples

Add a new attendee to an existing event.

>>> from icalendar import Event, vCalAddress
>>> event = Event()
>>> event.attendees.append(vCalAddress("mailto:me@my-domain.com"))
>>> print(event.to_ical())
BEGIN:VEVENT
ATTENDEE:mailto:me@my-domain.com
END:VEVENT

Create an email alarm with several attendees:

>>> from icalendar import Alarm, vCalAddress
>>> alarm = Alarm.new(attendees = [
...     vCalAddress("mailto:me@my-domain.com"),
...     vCalAddress("mailto:you@my-domain.com"),
... ], summary = "Email alarm")
>>> print(alarm.to_ical())
BEGIN:VALARM
ATTENDEE:mailto:me@my-domain.com
ATTENDEE:mailto:you@my-domain.com
SUMMARY:Email alarm
END:VALARM

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.

See also

Custom components for examples of parsing custom components

classmethod from_jcal(jcal)#

Create a component from a jCal list.

Parameters:

jcal (str | list) – jCal list or JSON string according to RFC 7265.

Raises:

JCalParsingError – If the jCal provided is invalid.
JSONDecodeError – If the provided string is not valid JSON.

Return type:

Component

This reverses to_json() and to_jcal().

The following code parses an example from RFC 7265:

>>> from icalendar import Component
>>> jcal = ["vcalendar",
...   [
...     ["calscale", {}, "text", "GREGORIAN"],
...     ["prodid", {}, "text", "-//Example Inc.//Example Calendar//EN"],
...     ["version", {}, "text", "2.0"]
...   ],
...   [
...     ["vevent",
...       [
...         ["dtstamp", {}, "date-time", "2008-02-05T19:12:24Z"],
...         ["dtstart", {}, "date", "2008-10-06"],
...         ["summary", {}, "text", "Planning meeting"],
...         ["uid", {}, "text", "4088E990AD89CB3DBB484909"]
...       ],
...       []
...     ]
...   ]
... ]
>>> calendar = Component.from_jcal(jcal)
>>> print(calendar.name)
VCALENDAR
>>> print(calendar.prodid)
-//Example Inc.//Example Calendar//EN
>>> event = calendar.events[0]
>>> print(event.summary)
Planning meeting

classmethod fromkeys(iterable, value=None)#: Create a new ordered dictionary with keys from iterable and values set to value.

get(key, default=None)#: Get property value with default.

classmethod get_component_class(name)#

Return a component with this name.

Parameters:: name (str) – Name of the component, i.e. VCALENDAR
Return type:: type[Component]

get_inline(name, decode=1)#: Returns a list of values (split on comma).

ignore_exceptions: ClassVar[bool] = False#

Whether or not to ignore exceptions when parsing.

If True, and this component can't be parsed, then it will silently ignore it, rather than let the exception propagate upwards.

property images: list[Image]#

IMAGE specifies an image associated with the calendar or a calendar component.

Description:: This property specifies an image for an iCalendar object or a calendar component via a URI or directly with inline data that can be used by calendar user agents when presenting the calendar data to a user. Multiple properties MAY be used to specify alternative sets of images with, for example, varying media subtypes, resolutions, or sizes. When multiple properties are present, calendar user agents SHOULD display only one of them, picking one that provides the most appropriate image quality, or display none. The "DISPLAY" parameter is used to indicate the intended display mode for the image. The "ALTREP" parameter, defined in RFC 5545, can be used to provide a "clickable" image where the URI in the parameter value can be "launched" by a click on the image in the calendar user agent.
Conformance:: This property can be specified multiple times in an iCalendar object or in "VEVENT", "VTODO", or "VJOURNAL" calendar components.

Note

At the present moment, this property is read-only. If you require a setter, please open an issue or a pull request.

inclusive: ClassVar[tuple[str] | tuple[tuple[str, str]]] = ()#

These properties are inclusive.

In other words, if the first property in the tuple occurs, then the second one must also occur.

Example

('duration', 'repeat')

is_empty()#: Returns True if Component has no items or subcomponents, else False.

is_thunderbird()#

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

Return type:: bool

items()#: Return a set-like object providing a view on the dict's items.

keys()#: Return a set-like object providing a view on the dict's keys.

property last_modified: datetime#

Datetime when the information associated with the component was last revised.

Since LAST_MODIFIED is an optional property, this returns DTSTAMP if LAST_MODIFIED is not set.

property links: list[vUri | vUid | vXmlReference]#

LINK properties as a list.

Purpose:

LINK provides a reference to external information related to a component.

Property Parameters:

The VALUE parameter is required. Non-standard, link relation type, format type, label, and language parameters can also be specified on this property. The LABEL parameter is defined in RFC 7986.

Conformance:

This property can be specified zero or more times in any iCalendar component. LINK is specified in RFC 9253. The LINKREL parameter is required.

Description:

When used in a component, the value of this property points to additional information related to the component. For example, it may reference the originating web server.

This property is a serialization of the model in RFC 8288, where the link target is carried in the property value, the link context is the containing calendar entity, and the link relation type and any target attributes are carried in iCalendar property parameters.

The LINK property parameters map to RFC 8288 attributes as follows:

LABEL: This parameter maps to the "title" attribute defined in Section 3.4.1 of RFC 8288. LABEL is used to label the destination of a link such that it can be used as a human-readable identifier (e.g., a menu entry) in the language indicated by the LANGUAGE (if present).
LANGUAGE: This parameter maps to the "hreflang" attribute defined in Section 3.4.1 of RFC 8288. See RFC 5646. Example: en, de-ch.
LINKREL: This parameter maps to the link relation type defined in Section 2.1 of RFC 8288. See Registered Link Relation Types.
FMTTYPE: This parameter maps to the "type" attribute defined in Section 3.4.1 of RFC 8288.

There is no mapping for "title*", "anchor", "rev", or "media" RFC 8288.

Examples

The following is an example of this property, which provides a reference to the source for the calendar object.

LINK;LINKREL=SOURCE;LABEL=Venue;VALUE=URI:
 https://example.com/events

The following is an example of this property, which provides a reference to an entity from which this one was derived. The link relation is a vendor-defined value.

LINK;LINKREL="https://example.com/linkrel/derivedFrom";
 VALUE=URI:
 https://example.com/tasks/01234567-abcd1234.ics

The following is an example of this property, which provides a reference to a fragment of an XML document. The link relation is a vendor-defined value.

LINK;LINKREL="https://example.com/linkrel/costStructure";
 VALUE=XML-REFERENCE:
 https://example.com/xmlDocs/bidFramework.xml
 #xpointer(descendant::CostStruc/range-to(
 following::CostStrucEND[1]))

Set a link icalendar.vUri to the event page:

>>> from icalendar import Event, vUri
>>> from datetime import datetime
>>> link = vUri(
...     "http://example.com/event-page",
...     params={"LINKREL":"SOURCE"}
... )
>>> event = Event.new(
...     start=datetime(2025, 9, 17, 12, 0),
...     summary="An Example Event with a page"
... )
>>> event.links = [link]
>>> print(event.to_ical())
BEGIN:VEVENT
SUMMARY:An Example Event with a page
DTSTART:20250917T120000
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
LINK;LINKREL="SOURCE":http://example.com/event-page
END:VEVENT

property location: str | None#

The intended venue for the activity defined by a calendar component.

Property Parameters:: IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.
Conformance:: Since RFC 5545, this property can be specified in "VEVENT" or "VTODO" calendar component. RFC 7953 adds this property to "VAVAILABILITY" and "VAVAILABLE".
Description:: Specific venues such as conference or meeting rooms may be explicitly specified using this property. An alternate representation may be specified that is a URI that points to directory information with more structured specification of the location. For example, the alternate representation may specify either an LDAP URL RFC 4516 pointing to an LDAP server entry or a CID URL RFC 2392 pointing to a MIME body part containing a Virtual-Information Card (vCard) RFC 2426 for the location.

move_to_end(key, last=True)#

Move an existing element to the end (or beginning if last is false).

Raise KeyError if the element does not exist.

multiple: ClassVar[tuple[()]] = ('ATTACH', 'ATTENDEE', 'CATEGORIES', 'COMMENT', 'CONTACT', 'EXDATE', 'RSTATUS', 'RELATED', 'RESOURCES', 'RDATE', 'RRULE')#: These properties may occur more than once.

name: ClassVar[str | None] = 'VTODO'#

The name of the component.

This should be defined in each component class.

Example: VCALENDAR.

classmethod new(attendees=None, categories=(), classification=None, color=None, comments=None, concepts=None, contacts=None, conferences=None, created=None, description=None, end=None, last_modified=None, links=None, location=None, organizer=None, priority=None, refids=None, related_to=None, sequence=None, stamp=None, start=None, status=None, summary=None, uid=None, url=None)[source]#

Create a new TODO with all required properties.

This creates a new Todo in accordance with RFC 5545.

Parameters:

attendees (list[vCalAddress] | None) – The attendees of the todo.
categories (Sequence[str]) – The categories of the todo.
classification (CLASS | None) – The classification of the todo.
color (str | None) – The color of the todo.
comments (list[str] | str | None) – The comments of the todo.
concepts (list[vUri | str] | str | vUri | None) – The concepts of the todo.
contacts (list[str] | str | None) – The contacts of the todo.
conferences (list[Conference] | None) – The conferences of the todo.
created (date | None) – The created of the todo.
description (str | None) – The description of the todo.
end (date | datetime | None) – The end of the todo.
last_modified (date | None) – The last_modified of the todo.
links (str | vUri | vUid | vXmlReference | None | list[str | vUri | vUid | vXmlReference]) – The links of the todo.
location (str | None) – The location of the todo.
organizer (vCalAddress | str | None) – The organizer of the todo.
refids (list[str] | str | None) – refids of the todo.
related_to (None | str | vText | vUri | vUid | list[str | vText | vUri | vUid]) – related_to of the todo.
sequence (int | None) – The sequence of the todo.
stamp (date | None) – The DTSTAMP of the todo. If None, this is set to the current time.
start (date | datetime | None) – The start of the todo.
status (STATUS | None) – The status of the todo.
summary (str | None) – The summary of the todo.
uid (str | UUID | None) – The uid of the todo. If None, this is set to a new uuid.uuid4().
url (str | None) – The url of the todo.

Returns:

Todo

Raises:

InvalidCalendar – If the content is not valid according to RFC 5545.

Warning

As time progresses, we will be stricter with the validation.

property organizer: vCalAddress | None#

ORGANIZER defines the organizer for a calendar component.

Property Parameters:

IANA, non-standard, language, common name, directory entry reference, and sent-by property parameters can be specified on this property.

Conformance:

This property MUST be specified in an iCalendar object that specifies a group-scheduled calendar entity. This property MUST be specified in an iCalendar object that specifies the publication of a calendar user's busy time. This property MUST NOT be specified in an iCalendar object that specifies only a time zone definition or that defines calendar components that are not group-scheduled components, but are components only on a single user's calendar.

Description:

This property is specified within the "VEVENT", "VTODO", and "VJOURNAL" calendar components to specify the organizer of a group-scheduled calendar entity. The property is specified within the "VFREEBUSY" calendar component to specify the calendar user requesting the free or busy time. When publishing a "VFREEBUSY" calendar component, the property is used to specify the calendar that the published busy time came from.

The property has the property parameters "CN", for specifying the common or display name associated with the "Organizer", "DIR", for specifying a pointer to the directory information associated with the "Organizer", "SENT-BY", for specifying another calendar user that is acting on behalf of the "Organizer". The non-standard parameters may also be specified on this property. If the "LANGUAGE" property parameter is specified, the identified language applies to the "CN" parameter value.

property priority: int#

Conformance:

This property can be specified in "VEVENT" and "VTODO" calendar components according to RFC 5545. RFC 7953 adds this property to "VAVAILABILITY".

Description:

This priority is specified as an integer in the range 0 to 9. A value of 0 specifies an undefined priority. A value of 1 is the highest priority. A value of 2 is the second highest priority. Subsequent numbers specify a decreasing ordinal priority. A value of 9 is the lowest priority.

A CUA with a three-level priority scheme of "HIGH", "MEDIUM", and "LOW" is mapped into this property such that a property value in the range of 1 to 4 specifies "HIGH" priority. A value of 5 is the normal or "MEDIUM" priority. A value in the range of 6 to 9 is "LOW" priority.

A CUA with a priority schema of "A1", "A2", "A3", "B1", "B2", …, "C3" is mapped into this property such that a property value of 1 specifies "A1", a property value of 2 specifies "A2", a property value of 3 specifies "A3", and so forth up to a property value of 9 specifies "C3".

Other integer values are reserved for future use.

Within a "VEVENT" calendar component, this property specifies a priority for the event. This property may be useful when more than one event is scheduled for a given time period.

Within a "VTODO" calendar component, this property specified a priority for the to-do. This property is useful in prioritizing multiple action items for a given time period.

property_items(recursive=True, sorted=True)#

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

Return type:: list[tuple[str, object]]

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 refids: list[str]#

REFID

Purpose:: REFID acts as a key for associated iCalendar entities.
Conformance:: Since RFC 9253, this property can be specified zero or more times in any iCalendar component.
Description:: The value of this property is free-form text that creates an identifier for associated components. All components that use the same REFID value are associated through that value and can be located or retrieved as a group. For example, all of the events in a travel itinerary would have the same REFID value, so as to be grouped together.

Examples

The following is an example of this property.

REFID:itinerary-2014-11-17

Use a REFID to associate several VTODOs:

>>> from icalendar import Todo
>>> todo_1 = Todo.new(
...     summary="turn off stove",
...     refids=["travel", "alps"]
... )
>>> todo_2 = Todo.new(
...     summary="pack backpack",
...     refids=["travel", "alps"]
... )
>>> todo_1.refids == todo_2.refids
True

Note

List modifications do not modify the component.

classmethod register(component_class)#

Register a custom component class.

Parameters:

component_class (type[Component]) – Component subclass to register. Must have a name attribute.

Raises:

ValueError – If component_class has no name attribute.
ValueError – If a component with this name is already registered.

Return type:

None

Examples

Create a custom icalendar component with the name X-EXAMPLE:

>>> from icalendar import Component
>>> class XExample(Component):
...     name = "X-EXAMPLE"
...     def custom_method(self):
...         return "custom"
>>> Component.register(XExample)

property related_to: list[vText | vUri | vUid]#

RELATED-TO properties as a list.

Purpose:

This property is used to represent a relationship or reference between one calendar component and another. RFC 9523 allows URI or UID values and a GAP parameter.

Value Type:

RFC 5545: TEXT RFC 9253: URI, UID

Conformance:

Since RFC 5545. this property can be specified in the "VEVENT", "VTODO", and "VJOURNAL" calendar components. Since RFC 9523, this property MAY be specified in any iCalendar component.

Description (RFC 5545):

The property value consists of the persistent, globally unique identifier of another calendar component. This value would be represented in a calendar component by the "UID" property.

By default, the property value points to another calendar component that has a PARENT relationship to the referencing object. The "RELTYPE" property parameter is used to either explicitly state the default PARENT relationship type to the referenced calendar component or to override the default PARENT relationship type and specify either a CHILD or SIBLING relationship. The PARENT relationship indicates that the calendar component is a subordinate of the referenced calendar component. The CHILD relationship indicates that the calendar component is a superior of the referenced calendar component. The SIBLING relationship indicates that the calendar component is a peer of the referenced calendar component.

Changes to a calendar component referenced by this property can have an implicit impact on the related calendar component. For example, if a group event changes its start or end date or time, then the related, dependent events will need to have their start and end dates changed in a corresponding way. Similarly, if a PARENT calendar component is cancelled or deleted, then there is an implied impact to the related CHILD calendar components. This property is intended only to provide information on the relationship of calendar components. It is up to the target calendar system to maintain any property implications of this relationship.

Description (RFC 9253):

By default or when VALUE=UID is specified, the property value consists of the persistent, globally unique identifier of another calendar component. This value would be represented in a calendar component by the UID property.

By default, the property value points to another calendar component that has a PARENT relationship to the referencing object. The RELTYPE property parameter is used to either explicitly state the default PARENT relationship type to the referenced calendar component or to override the default PARENT relationship type and specify either a CHILD or SIBLING relationship or a temporal relationship.

The PARENT relationship indicates that the calendar component is a subordinate of the referenced calendar component. The CHILD relationship indicates that the calendar component is a superior of the referenced calendar component. The SIBLING relationship indicates that the calendar component is a peer of the referenced calendar component.

To preserve backwards compatibility, the value type MUST be UID when the PARENT, SIBLING, or CHILD relationships are specified.

The FINISHTOSTART, FINISHTOFINISH, STARTTOFINISH, or STARTTOSTART relationships define temporal relationships, as specified in the RELTYPE parameter definition.

The FIRST and NEXT define ordering relationships between calendar components.

The DEPENDS-ON relationship indicates that the current calendar component depends on the referenced calendar component in some manner. For example, a task may be blocked waiting on the other, referenced, task.

The REFID and CONCEPT relationships establish a reference from the current component to the referenced component. Changes to a calendar component referenced by this property can have an implicit impact on the related calendar component. For example, if a group event changes its start or end date or time, then the related, dependent events will need to have their start and end dates and times changed in a corresponding way. Similarly, if a PARENT calendar component is canceled or deleted, then there is an implied impact to the related CHILD calendar components. This property is intended only to provide information on the relationship of calendar components.

Deletion of the target component, for example, the target of a FIRST, NEXT, or temporal relationship, can result in broken links.

It is up to the target calendar system to maintain any property implications of these relationships.

Examples

RFC 5545 examples of this property:

RELATED-TO:jsmith.part7.19960817T083000.xyzMail@example.com

RELATED-TO:19960401-080045-4000F192713-0052@example.com

RFC 9253 examples of this property:

RELATED-TO;VALUE=URI;RELTYPE=STARTTOFINISH:
 https://example.com/caldav/user/jb/cal/
 19960401-080045-4000F192713.ics

icalendar.cal.todo module#

This Page