icalendar.cal.component module#
The base for RFC 5545 components.
- class icalendar.cal.component.Component(*args, **kwargs)[source]#
Bases:
CaselessDict
Base class for calendar components.
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.
- name#
The name of the component. Example:
VCALENDAR
.
- required#
These properties are required.
- singletons#
These properties must only appear once.
- multiple#
These properties may occur more than once.
- exclusive#
These properties are mutually exclusive.
- inclusive#
If the first in a tuple occurs, the second one must also occur.
- ignore_exceptions#
If True, and we cannot parse this component, we will silently ignore it, rather than let the exception propagate upwards.
- types_factory#
Factory for property types
- 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 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: str, value, parameters: dict[str, str] | Parameters = None, encode: bool = True)[source]#
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
- property comments: list[str]#
COMMENT is used to specify a comment to the calendar user.
- Purpose:
This property specifies non-processing information intended to provide a comment to the calendar user.
- Conformance:
In RFC 5545, this property can be specified multiple times in “VEVENT”, “VTODO”, “VJOURNAL”, and “VFREEBUSY” calendar components as well as in the “STANDARD” and “DAYLIGHT” sub-components. In RFC 7953, this property can be specified multiple times in “VAVAILABILITY” and “VAVAILABLE”.
- Property Parameters:
IANA, non-standard, alternate text representation, and language property parameters can be specified on this property.
- content_lines(sorted: bool = True)[source]#
Converts the Component and subcomponents into content lines.
- property created: datetime#
Datetime when the information associated with the component was created.
Since
CREATED
is an optional property, this returnsDTSTAMP
ifCREATED
is not set.
- exclusive = ()#
- classmethod from_ical(st, multiple: bool = False) Self | list[Self] [source]#
Populates the component recursively from a string.
- classmethod get_component_class(name: str) type[Component] [source]#
Return a component with this name.
- Parameters:
name – Name of the component, i.e.
VCALENDAR
- ignore_exceptions = False#
- is_thunderbird() bool [source]#
Whether this component has attributes that indicate that Mozilla Thunderbird created it.
- property last_modified: datetime#
Datetime when the information associated with the component was last revised.
Since
LAST_MODIFIED
is an optional property, this returnsDTSTAMP
ifLAST_MODIFIED
is not set.
- multiple = ()#
- name = None#
- classmethod new(created: date | None = None, comments: list[str] | str | None = None, last_modified: date | None = None, stamp: date | None = None) Component [source]#
Create a new component.
- Parameters:
comments – The
comments
of the component.created – The
created
of the component.last_modified – The
last_modified
of the component.stamp – The
DTSTAMP
of the component.
- Raises:
InvalidCalendar – If the content is not valid according to RFC 5545.
Warning
As time progresses, we will be stricter with the validation.
- property_items(recursive=True, sorted: bool = True) list[tuple[str, object]] [source]#
Returns properties in this component and subcomponents as: [(name, value), …]
- required = ()#
- set_inline(name, values, encode=1)[source]#
Converts a list of values into comma separated string and sets value to that.
- singletons = ()#
- property stamp: 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.
- to_ical(sorted: bool = True)[source]#
- Parameters:
sorted – Whether parameters and properties should be lexicographically sorted.
- types_factory = {'BINARY': <class 'icalendar.prop.vBinary'>, 'BOOLEAN': <class 'icalendar.prop.vBoolean'>, 'CAL-ADDRESS': <class 'icalendar.prop.vCalAddress'>, 'CATEGORIES': <class 'icalendar.prop.vCategory'>, 'DATE': <class 'icalendar.prop.vDDDTypes'>, 'DATE-TIME': <class 'icalendar.prop.vDDDTypes'>, 'DATE-TIME-LIST': <class 'icalendar.prop.vDDDLists'>, 'DURATION': <class 'icalendar.prop.vDDDTypes'>, 'FLOAT': <class 'icalendar.prop.vFloat'>, 'GEO': <class 'icalendar.prop.vGeo'>, 'INLINE': <class 'icalendar.prop.vInline'>, 'INTEGER': <class 'icalendar.prop.vInt'>, 'PERIOD': <class 'icalendar.prop.vPeriod'>, 'RECUR': <class 'icalendar.prop.vRecur'>, 'TEXT': <class 'icalendar.prop.vText'>, 'TIME': <class 'icalendar.prop.vTime'>, 'URI': <class 'icalendar.prop.vUri'>, 'UTC-OFFSET': <class 'icalendar.prop.vUTCOffset'>}#
- 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