icalendar.cal.free_busy module#

RFC 5545 VFREEBUSY component.

class icalendar.cal.free_busy.FreeBusy(*args, **kwargs)[source]#

Bases: Component

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.

Examples

Create a new FreeBusy:

>>> from icalendar import FreeBusy
>>> free_busy = FreeBusy.new()
>>> print(free_busy.to_ical())
BEGIN:VFREEBUSY
DTSTAMP:20250517T080612Z
UID:d755cef5-2311-46ed-a0e1-6733c9e15c63
END:VFREEBUSY
property DTEND: date | None#

The DTEND property.

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

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 “VFREEBUSY” specifies the inclusive start of the component.

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

Contact information associated with the calendar component.

Purpose:

This property is used to represent contact information or alternately a reference to contact information associated with the calendar component.

Property Parameters:

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

Conformance:

In RFC 5545, this property can be specified in a “VEVENT”, “VTODO”, “VJOURNAL”, or “VFREEBUSY” calendar component. In RFC 7953, this property can be specified in a “VAVAILABILITY” amd “VAVAILABLE” calendar component.

Description:

The property value consists of textual contact information. An alternative representation for the property value can also be specified that refers to a URI pointing to an alternate form, such as a vCard RFC 2426, for the contact information.

Example

The following is an example of this property referencing textual contact information:

CONTACT:Jim Dolittle\, ABC Industries\, +1-919-555-1234

The following is an example of this property with an alternate representation of an LDAP URI to a directory entry containing the contact information:

CONTACT;ALTREP="ldap://example.com:6666/o=ABC%20Industries\,
c=US???(cn=Jim%20Dolittle)":Jim Dolittle\, ABC Industries\,
+1-919-555-1234

The following is an example of this property with an alternate representation of a MIME body part containing the contact information, such as a vCard RFC 2426 embedded in a text/ directory media type RFC 2425:

CONTACT;ALTREP="CID:part3.msg970930T083000SILVER@example.com":
 Jim Dolittle\, ABC Industries\, +1-919-555-1234

The following is an example of this property referencing a network resource, such as a vCard RFC 2426 object containing the contact information:

CONTACT;ALTREP="http://example.com/pdi/jdoe.vcf":Jim
 Dolittle\, ABC Industries\, +1-919-555-1234
property duration: timedelta | None#

The duration computed from start and end.

property end: date | None#

The DTEND property.

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

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.

multiple = ('ATTENDEE', 'COMMENT', 'FREEBUSY', 'RSTATUS')#
name = 'VFREEBUSY'#
classmethod new(comments: list[str] | str | None = None, contacts: list[str] | str | None = None, end: date | datetime | None = None, organizer: vCalAddress | str | None = None, stamp: date | None = None, start: date | datetime | None = None, uid: str | uuid.UUID | None = None, url: str | None = None)[source]#

Create a new alarm with all required properties.

This creates a new Alarm in accordance with RFC 5545.

Parameters:

  • comments – The Component.comments of the component.

  • organizer – The organizer of the component.

  • stamp – The DTSTAMP of the component. If None, this is set to the current time.

  • uid – The uid of the component. If None, this is set to a new uuid.uuid4().

  • url – The url of the component.

Returns:

FreeBusy

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.

required = ('UID', 'DTSTAMP')#
singletons = ('CONTACT', 'DTSTART', 'DTEND', 'DTSTAMP', 'ORGANIZER', 'UID', 'URL')#
property start: date | None#

The DTSTART property.

The “DTSTART” property for a “VFREEBUSY” specifies the inclusive start of the component.

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.

subcomponents: list[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
property url: str#

A Uniform Resource Locator (URL) associated with the iCalendar object.

Description:

This property may be used in a calendar component to convey a location where a more dynamic rendition of the calendar information associated with the calendar component can be found. This memo does not attempt to standardize the form of the URI, nor the format of the resource pointed to by the property value. If the URL property and Content-Location MIME header are both specified, they MUST point to the same resource.

Conformance:

This property can be specified once in the “VEVENT”, “VTODO”, “VJOURNAL”, or “VFREEBUSY” calendar components. Since RFC 7986, this property can also be defined on a “VCALENDAR”.

Example

The following is an example of this property:

URL:http://example.com/pub/calendars/jsmith/mytime.ics