icalendar.cal.available module#

This implements the sub-component "AVAILABLE" of "VAVAILABILITY".

This is specified in RFC 7953.

class icalendar.cal.available.Available(*args, **kwargs)[source]#

Bases: Component

Sub-component of "VAVAILABILITY from RFC 7953.

Description:: "AVAILABLE" subcomponents are used to indicate periods of free time within the time range of the enclosing "VAVAILABILITY" component. "AVAILABLE" subcomponents MAY include recurrence properties to specify recurring periods of time, which can be overridden using normal iCalendar recurrence behavior (i.e., use of the "RECURRENCE-ID" property).

Examples

This is a recurring "AVAILABLE" subcomponent:

BEGIN:AVAILABLE
UID:57DD4AAF-3835-46B5-8A39-B3B253157F01
SUMMARY:Monday to Friday from 9:00 to 17:00
DTSTART;TZID=America/Denver:20111023T090000
DTEND;TZID=America/Denver:20111023T170000
RRULE:FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR
LOCATION:Denver
END:AVAILABLE

You can get the same example from example():

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 DTEND: datetime | None#

The DTEND property. datetime in UTC

All values will be converted to a datetime in UTC. Start of the component.

This is almost the same as Event.DTEND with one exception: The values MUST have a timezone and DATE is not allowed.

Description:: RFC 7953: If specified, the "DTSTART" and "DTEND" properties in "VAVAILABILITY" components and "AVAILABLE" subcomponents MUST be "DATE-TIME" values specified as either the date with UTC time or the date with local time and a time zone reference.

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: datetime | None#

The DTSTART property. datetime in UTC

All values will be converted to a datetime in UTC. Start of the component.

This is almost the same as Event.DTSTART with one exception: The values MUST have a timezone and DATE is not allowed.

Description:: RFC 7953: If specified, the "DTSTART" and "DTEND" properties in "VAVAILABILITY" components and "AVAILABLE" subcomponents MUST be "DATE-TIME" values specified as either the date with UTC time or the date with local time and a time zone reference.

property DURATION: timedelta | None#

The DURATION property.

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

If you would like to calculate the duration of a Available, 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.

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

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[()]] = ()#: These properties may occur more than once.

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

The name of the component.

This should be defined in each component class.

Example: VCALENDAR.

classmethod new(categories=(), comments=None, concepts=None, contacts=None, created=None, description=None, end=None, last_modified=None, links=None, location=None, refids=None, related_to=None, sequence=None, stamp=None, start=None, summary=None, uid=None)[source]#

Create a new Available component with all required properties.

This creates a new Available component in accordance with RFC 7953.

Parameters:

categories (Sequence[str]) – The categories of the Available component.
comments (list[str] | str | None) – The comments of the Available component.
concepts (list[vUri | str] | str | vUri | None) – The concepts of the Available component.
contacts (list[str] | str | None) – The contacts of the Available component.
created (date | None) – The created of the Available component.
description (str | None) – The description of the Available component.
end (datetime | None) – The end of the Available component.
last_modified (date | None) – The last_modified of the Available component.
links (str | vUri | vUid | vXmlReference | None | list[str | vUri | vUid | vXmlReference]) – The links of the Available component.
location (str | None) – The location of the Available component.
refids (list[str] | str | None) – refids of the Available component.
related_to (None | str | vText | vUri | vUid | list[str | vText | vUri | vUid]) – related_to of the Available component.
sequence (int | None) – The sequence of the Available component.
stamp (date | None) – The stamp of the Available component. If None, this is set to the current time.
start (datetime | None) – The start of the Available component.
summary (str | None) – The summary of the Available component.
uid (str | UUID | None) – The uid of the Available component. If None, this is set to a new uuid.uuid4().

Returns:

Available

Raises:

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

Warning

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

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.available module#

This Page