icalendar.attr package#

Submodules#

Module contents#

Attributes of Components and properties.

icalendar.attr.create_single_property(prop, value_attr, value_type, type_def, doc, vProp=<class 'icalendar.prop.dt.types.vDDDTypes'>, convert=None)[source]#

Create a single property getter and setter.

Parameters:

  • prop (str) – The name of the property.

  • value_attr (str | None) – The name of the attribute to get the value from.

  • value_type (tuple[type]) – The type of the value.

  • type_def (type) – The type of the property.

  • doc (str) – The docstring of the property.

  • vProp (type) – The type of the property from icalendar.prop.

icalendar.attr.duration_property(component)[source]#

Return the duration property.

Return type:

property

icalendar.attr.get_duration_property(component)[source]#

Get the duration property with fallback calculation from start and end.

Parameters:

component (Event | Todo) – The component from which to get its duration property.

Return type:

timedelta

Returns:

The duration as a timedelta.

icalendar.attr.get_end_property(component, end_property)[source]#

Get the end property with fallback logic for Event and Todo components.

Parameters:

  • component (Event | Todo) – The component to get end from

  • end_property (Literal['DTEND', 'DUE']) – The end property name, either DTEND for Event or DUE for Todo.

Return type:

date | datetime

Returns:

The computed end value.

Raises:

IncompleteComponent – If the provided information is incomplete to compute the end property.

icalendar.attr.get_start_end_duration_with_validation(component, start_property, end_property, component_name)[source]#

Validate the component and return start, end, and duration.

This tests validity according to RFC 5545 rules for Event and Todo components.

Parameters:

  • component (Event | Todo) – The component to validate, either Event or Todo.

  • start_property (Literal['DTSTART']) – The start property name, DTSTART.

  • end_property (Literal['DTEND', 'DUE']) – The end property name, either DTEND for Event or DUE for Todo.

  • component_name (Literal['VEVENT', 'VTODO']) – The component name for error messages, either VEVENT or VTODO.

Returns:

(start, end, duration) values from the component.

Return type:

tuple[date | datetime | None, date | datetime | None, timedelta | None]

Raises:

InvalidCalendar – If the component violates RFC 5545 constraints.

icalendar.attr.get_start_property(component)[source]#

Get the start property with validation.

Parameters:

component (Event | Todo) – The component from which to get its start property.

Return type:

date | datetime

Returns:

The DTSTART value.

Raises:

IncompleteComponent – If no DTSTART is present.

icalendar.attr.multi_language_text_property(main_prop, compatibility_prop, doc)[source]#

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 | None) – An old property used before, such as X-WR-CALNAME

  • doc (str) – The documentation string

Return type:

property

icalendar.attr.multi_string_property(name, doc)[source]#

A property for an iCalendar Property that can occur multiple times.

icalendar.attr.multi_text_property(name, docs)[source]#

Get a property that can occur several times and is text.

Examples: Journal.descriptions, Event.comments

Return type:

property

icalendar.attr.property_del_duration(self)[source]#

Delete property DURATION.

icalendar.attr.property_get_duration(self)[source]#

Getter for property DURATION.

Return type:

timedelta | None

icalendar.attr.property_set_duration(self, value)[source]#

Setter for property DURATION.

icalendar.attr.set_duration_with_locking(component, duration, locked, end_property)[source]#

Set the duration with explicit locking behavior for Event and Todo.

Parameters:

  • component (Event | Todo) – The component to modify, either Event or Todo.

  • duration (timedelta | None) – The duration to set, or None to convert to DURATION property.

  • locked (Literal['start', 'end']) – Which property to keep unchanged, either start or end.

  • end_property (Literal['DTEND', 'DUE']) – The end property name, either DTEND for Event or DUE for Todo.

Return type:

None

icalendar.attr.set_end_with_locking(component, end, locked, end_property)[source]#

Set the end with explicit locking behavior for Event and Todo components.

Parameters:

  • component (Event | Todo) – The component to modify, either Event or Todo.

  • end (date | datetime) – The end time to set.

  • locked (Literal['start', 'duration']) – Which property to keep unchanged, either start or duration.

  • end_property (Literal['DTEND', 'DUE']) – The end property name, either DTEND for Event or DUE for Todo.

Return type:

None

icalendar.attr.set_start_with_locking(component, start, locked, end_property)[source]#

Set the start with explicit locking behavior for Event and Todo components.

Parameters:

  • component (Event | Todo) – The component to modify, either Event or Todo.

  • start (date | datetime) – The start time to set.

  • locked (Literal['duration', 'end'] | None) – Which property to keep unchanged, either duration, end, or None for auto-detect.

  • end_property (Literal['DTEND', 'DUE']) – The end property name, either DTEND for Event or DUE for Todo.

Return type:

None

icalendar.attr.single_int_property(prop, default, doc, *, min_value=None)[source]#

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

Parameters:

  • default (int) – Required. The default value.

  • doc (str) – Required. The documentation string.

  • prop (str) – Required. The name of the property.

  • min_value (int | None) – If set, the value must be greater than or equal to this minimum.

Return type:

property

Added in version 7.3.0: Added the min_value parameter.

icalendar.attr.single_string_enum_property(name, enum, default, docs)[source]#

Create a property to access a single string value and convert it to an enum.

Return type:

property

icalendar.attr.single_string_property(name, docs, other_name=None, default='', validate=None)[source]#

Create a property to access a single string value.

Parameters:

  • docs (str) – Required. Documentation string for the generated property.

  • name (str) – Required. The iCalendar property name, such as UID.

  • default (str) – Value returned when the property is not set.

  • other_name (str | list[str] | None) – One or more alias names to fall back on when the primary name is not present in the component.

  • validate (Callable[[str], None] | None) – Callable that receives the string form of the value and raises an exception if it does not conform to the expected format. It is called on set, before any existing value is removed, and must not modify the value.

Return type:

property

icalendar.attr.single_utc_property(name, docs)[source]#

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

Parameters:

  • name (str) – name of the property

  • docs (str) – documentation string

Return type:

property

icalendar.attr.validate_uid(value)[source]#

Validate the given value as a well-formed UID.

When set, the value must be an RFC 5545 Section 3.1 iana-token consisting of only ASCII letters, digits, and hyphens, and shorter than 255 octets, as required by RFC 7986 Section 5.3.

Parameters:

value (str) – The string form of the UID to validate.

Raises:

InvalidCalendar – If value is not compliant with RFC 5545 Section 3.1 as an iana-token or is 255 octets or longer.

Return type:

None