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

Get the example FreeBusy.

>>> from icalendar import FreeBusy
>>> free_busy = FreeBusy.example()
>>> print(free_busy.to_ical().decode())
BEGIN:VFREEBUSY
DTEND:19980410T234500Z
DTSTAMP:19970901T120000Z
DTSTART:19980313T141711Z
FREEBUSY:19980314T233000Z/19980315T003000Z
FREEBUSY:19980316T153000Z/19980316T163000Z
FREEBUSY:19980318T030000Z/19980318T040000Z
ORGANIZER:jsmith@example.com
UID:19970901T115957Z-76A912@example.com
URL:http://www.example.com/calendar/busytime/jsmith.ifb
END:VFREEBUSY

Set keys to upper for initial dict.

property DTEND: date | None#

The DTEND property.

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

To delete the value, either use del or set it to None.

Raises:

InvalidCalendar – if the attribute has invalid values.

property DTSTART: date | None#

The DTSTART property.

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

To delete the value, either use del or set it to None.

Raises:

InvalidCalendar – if the attribute has invalid values.

property REQUEST_STATUS: PropertyListView#

This property defines the status code returned for a scheduling request.

You can assign a single string, a list of strings, or None to this property. The property stores a str as-is. Assigning None or an empty list removes all REQUEST-STATUS values, as does deleting the property.

The value consists of a short return status code component, a longer return status description component, and optionally a status-specific data component, separated by semicolons (statcode;statdesc[;extdata]). The return status components are defined in RFC 5545 Section 3.8.8.3.

The REQUEST-STATUS property can be specified in the following icalendar components as REQUEST_STATUS.

Note

When you assign a list to this property, the returned list is the same object stored in the component. Modifying it (append(), extend(), remove(), item assignment, or del) changes what the component stores.

However, if you assign a single string value to this property, the returned list is a temporary copy, and changes to this list don't affect the component.

Parameters:

request_status (str | list[str] | None) – Either a single status string, a list of status strings, or None to set the component's status code returned for a scheduling request.

Example

Add a request status to an event:

>>> from icalendar import Event
>>> event = Event.new(request_status="2.0;Success")
>>> event.REQUEST_STATUS == ["2.0;Success"]
True

vRequestStatus defines properties for ease of use:

>>> request_status = event.REQUEST_STATUS[0]
>>> request_status.code
(2, 0)
>>> request_status.description
'Success'
Setter accepts:

list[str] | str | None

property contacts: list[str]#

Contact information associated with a calendar component.

The contact property holds free-text information for reaching the person or organization responsible in a component, such as a name, phone number, or a reference to more detailed contact data. Calendar clients surface it so attendees know who to contact about the event or task.

This property is defined in RFC 5545 Section 3.8.4.2 and may appear on a VEVENT, VTODO, VJOURNAL, or VFREEBUSY component. For availability components it is defined in RFC 7953 and may appear on a VAVAILABILITY or VAVAILABLE component. An alternate representation may point to a URI, for example, a vCard per RFC 2426, via the ALTREP parameter.

You can get, set, append, and delete contacts on a component. The value is a list of strings; each string is one contact entry.

Example

Add a contact to an event and then read it back.

>>> from icalendar import Event
>>> event = Event()
>>> event.add("CONTACT", "Jim Dolittle, ABC Industries, +1-919-555-1234")
>>> [str(c) for c in event.contacts]
['Jim Dolittle, ABC Industries, +1-919-555-1234']
>>> str(event.contacts[0])
'Jim Dolittle, ABC Industries, +1-919-555-1234'
Setter accepts:

str | Sequence[str] | None

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.

To delete the value, either use del or set it to None.

Raises:

InvalidCalendar – if the attribute has invalid values.

classmethod example(name='example')[source]#

Return the FreeBusy example with the given name.

Return type:

FreeBusy

multiple: ClassVar[tuple[()]] = ('ATTENDEE', 'COMMENT', 'FREEBUSY', 'REQUEST-STATUS')#

These properties may occur more than once.

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

The name of the component.

This is defined in each component class.

Example

>>> from icalendar import Calendar
>>> cal = Calendar.new()
>>> cal.name
'VCALENDAR'
classmethod new(comments=None, concepts=None, contacts=None, end=None, links=None, organizer=None, refids=None, related_to=None, request_status=None, stamp=None, start=None, uid=None, url=None)[source]#

Create a new FreeBusy component with all required properties, in accordance with RFC 5545 Section 3.6.4.

The FreeBusy component has the required properties of UID and DTSTAMP, which may be set with the parameters of uid and stamp.

Parameters:
Return type:

Self

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.

Setter accepts:

vCalAddress | str | None

required: ClassVar[tuple[()]] = ('UID', 'DTSTAMP')#

These properties are required.

singletons: ClassVar[tuple[()]] = ('CONTACT', 'DTSTART', 'DTEND', 'DTSTAMP', 'ORGANIZER', 'UID', 'URL')#

These properties must appear only once.

property start: date | None#

The DTSTART property.

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

To delete the value, either use del or set it to None.

Raises:

InvalidCalendar – if the attribute has invalid values.

property uid: str#

UID specifies the persistent, globally unique identifier for a component.

It's generated automatically when calling Event.new, Todo.new, or Journal.new.

To manually set, use uuid.uuid4() to generate new values, and the class's uid property. When set, the value must be an RFC 5545 iana-token consisting of only ASCII letters, digits, and hyphens, and be shorter than 255 octets, as required by RFC 7986 Section 5.3. To clear the value, set it to "" or None. Values that do not conform raise InvalidCalendar.

Returns:

The value of the UID property as a string, or "" if no value is set.

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

Set a new UUID4 as the UID (recommended):

>>> from icalendar import Event
>>> from uuid import uuid4
>>> event = Event()
>>> event.uid = uuid4()
>>> event.uid
vText(b'...')

Setting a valid token preserves its casing, while an invalid value raises an error:

>>> event.uid = "AbC-123"  # a valid token, casing is preserved
>>> print(event.uid)
AbC-123
>>> event.uid = "a b"
Traceback (most recent call last):
  ...
icalendar.error.InvalidCalendar: UID must be an RFC 5545 iana-token, got 'a b'

See also

Setter accepts:

str | None

property url: str#

A Uniform Resource Locator (URL) associated with a calendar component.

This property specifies a URI where a more dynamic rendition of the calendar information can be found. It is commonly used to reference related resources or provide additional information about the component.

According to RFC 5545 Section 3.8.4.6, this property can be specified once in "VEVENT", "VTODO", "VJOURNAL", or "VFREEBUSY" calendar components. Since RFC 7986 Section 5.5, this property can also be defined on a "VCALENDAR". RFC 7953 Section 3.1 allows this property in "VAVAILABILITY" components.

This property may be used in a calendar component to convey a location where a more dynamic rendition of the calendar information can be found. If both the URL property and Content-Location MIME header are specified, they MUST point to the same resource.

This differs from the SOURCE property, which identifies where calendar data can be refreshed from, whereas URL provides an alternative representation of the current calendar data.

Examples

Set a URL for an event that references additional information:

>>> from icalendar import Event
>>> event = Event()
>>> event.add('url', 'http://example.com/events/meeting-2025')
>>> print(event.to_ical().decode('utf-8'))
BEGIN:VEVENT
URL:http://example.com/events/meeting-2025
END:VEVENT

Set a URL for a calendar:

>>> from icalendar import Calendar
>>> calendar = Calendar()
>>> calendar.add('url', 'http://example.com/pub/calendars/jsmith/mytime.ics')
>>> print(calendar.to_ical().decode('utf-8'))
BEGIN:VCALENDAR
URL:http://example.com/pub/calendars/jsmith/mytime.ics
END:VCALENDAR

See also

source for specifying from where calendar data can be refreshed.

icalendar implementations:

Setter accepts:

str | None