icalendar.prop package#

This module contains the parser/generators (or coders/encoders if you prefer) for the classes/datatypes that are used in iCalendar:

# This module defines these property value data types and property parameters

4.2 Defined property parameters are:

ALTREP, CN, CUTYPE, DELEGATED-FROM, DELEGATED-TO, DIR, ENCODING, FMTTYPE,
FBTYPE, LANGUAGE, MEMBER, PARTSTAT, RANGE, RELATED, RELTYPE, ROLE, RSVP,
SENT-BY, TZID, VALUE

4.3 Defined value data types are:

BINARY, BOOLEAN, CAL-ADDRESS, DATE, DATE-TIME, DURATION, FLOAT, INTEGER,
PERIOD, RECUR, TEXT, TIME, URI, UTC-OFFSET

iCalendar properties have values. The values are strongly typed. This module defines these types, calling val.to_ical() on them will render them as defined in rfc5545.

If you pass any of these classes a Python primitive, you will have an object that can render itself as iCalendar formatted date.

Property Value Data Types start with a ‘v’. they all have an to_ical() and from_ical() method. The to_ical() method generates a text string in the iCalendar format. The from_ical() method can parse this format and return a primitive Python datatype. So it should always be true that:

x == vDataType.from_ical(VDataType(x).to_ical())

These types are mainly used for parsing and file generation. But you can set them directly.

class icalendar.prop.TimeBase[source]#

Bases: object

Make classes with a datetime/date comparable.

property RANGE: RANGE | str | None#

Specify the effective range of recurrence instances from the instance specified by the recurrence identifier specified by the property.

Description:

This parameter can be specified on a property that specifies a recurrence identifier. The parameter specifies the effective range of recurrence instances that is specified by the property. The effective range is from the recurrence identifier specified by the property. If this parameter is not specified on an allowed property, then the default range is the single instance specified by the recurrence identifier value of the property. The parameter value can only be “THISANDFUTURE” to indicate a range defined by the recurrence identifier and all subsequent instances. The value “THISANDPRIOR” is deprecated by this revision of iCalendar and MUST NOT be generated by applications.

property RELATED: RELATED | str#

Specify the relationship of the alarm trigger with respect to the start or end of the calendar component.

Description:

This parameter can be specified on properties that specify an alarm trigger with a “DURATION” value type. The parameter specifies whether the alarm will trigger relative to the start or end of the calendar component. The parameter value START will set the alarm to trigger off the start of the calendar component; the parameter value END will set the alarm to trigger off the end of the calendar component. If the parameter is not specified on an allowable property, then the default is START.

property TZID: str | None#

Specify the identifier for the time zone definition for a time component in the property value.

Description:

This parameter MUST be specified on the “DTSTART”, “DTEND”, “DUE”, “EXDATE”, and “RDATE” properties when either a DATE-TIME or TIME value type is specified and when the value is neither a UTC or a “floating” time. Refer to the DATE-TIME or TIME value type definition for a description of UTC and “floating time” formats. This property parameter specifies a text value that uniquely identifies the “VTIMEZONE” calendar component to be used when evaluating the time portion of the property. The value of the “TZID” property parameter will be equal to the value of the “TZID” property for the matching time zone definition. An individual “VTIMEZONE” calendar component MUST be specified for each unique “TZID” parameter value specified in the iCalendar object.

The parameter MUST be specified on properties with a DATE-TIME value if the DATE-TIME is not either a UTC or a “floating” time. Failure to include and follow VTIMEZONE definitions in iCalendar objects may lead to inconsistent understanding of the local time at any given location.

The presence of the SOLIDUS character as a prefix, indicates that this “TZID” represents a unique ID in a globally defined time zone registry (when such registry is defined).

Note

This document does not define a naming convention for time zone identifiers. Implementers may want to use the naming conventions defined in existing time zone specifications such as the public-domain TZ database (TZDB). The specification of globally unique time zone identifiers is not addressed by this document and is left for future study.

ignore_for_equality = {'TZID', 'VALUE'}#
params: Parameters#
class icalendar.prop.TypesFactory(*args, **kwargs)[source]#

Bases: CaselessDict

All Value types defined in RFC 5545 are registered in this factory class.

The value and parameter names don’t overlap. So one factory is enough for both kinds.

for_property(name)[source]#

Returns a the default type for a property or parameter

from_ical(name, value)[source]#

Decodes a named property or parameter value from an icalendar encoded string to a primitive python type.

to_ical(name, value)[source]#

Encodes a named value from a primitive python type to an icalendar encoded string.

types_map = {'ACKNOWLEDGED': 'date-time', 'ACTION': 'text', 'ALTREP': 'uri', 'ATTACH': 'uri', 'ATTENDEE': 'cal-address', 'CALSCALE': 'text', 'CATEGORIES': 'categories', 'CLASS': 'text', 'CN': 'text', 'COMMENT': 'text', 'COMPLETED': 'date-time', 'CONFERENCE': 'uri', 'CONTACT': 'text', 'CREATED': 'date-time', 'CUTYPE': 'text', 'DELEGATED-FROM': 'cal-address', 'DELEGATED-TO': 'cal-address', 'DESCRIPTION': 'text', 'DIR': 'uri', 'DTEND': 'date-time', 'DTSTAMP': 'date-time', 'DTSTART': 'date-time', 'DUE': 'date-time', 'DURATION': 'duration', 'ENCODING': 'text', 'EXDATE': 'date-time-list', 'EXRULE': 'recur', 'FBTYPE': 'text', 'FMTTYPE': 'text', 'FREEBUSY': 'period', 'GEO': 'geo', 'LANGUAGE': 'text', 'LAST-MODIFIED': 'date-time', 'LOCATION': 'text', 'MEMBER': 'cal-address', 'METHOD': 'text', 'ORGANIZER': 'cal-address', 'PARTSTAT': 'text', 'PERCENT-COMPLETE': 'integer', 'PRIORITY': 'integer', 'PRODID': 'text', 'RANGE': 'text', 'RDATE': 'date-time-list', 'RECURRENCE-ID': 'date-time', 'REFRESH-INTERVAL': 'duration', 'RELATED': 'text', 'RELATED-TO': 'text', 'RELTYPE': 'text', 'REPEAT': 'integer', 'REQUEST-STATUS': 'text', 'RESOURCES': 'text', 'ROLE': 'text', 'RRULE': 'recur', 'RSVP': 'boolean', 'SENT-BY': 'cal-address', 'SEQUENCE': 'integer', 'SOURCE': 'uri', 'STATUS': 'text', 'SUMMARY': 'text', 'TRANSP': 'text', 'TRIGGER': 'duration', 'TZID': 'text', 'TZNAME': 'text', 'TZOFFSETFROM': 'utc-offset', 'TZOFFSETTO': 'utc-offset', 'TZURL': 'uri', 'UID': 'text', 'URL': 'uri', 'VALUE': 'text', 'VERSION': 'text'}#
icalendar.prop.tzid_from_dt(dt: datetime) → str | None[source]#

Retrieve the timezone id from the datetime object.

icalendar.prop.tzid_from_tzinfo(tzinfo: tzinfo | None) → str | None[source]#

Retrieve the timezone id from the tzinfo object.

Some timezones are equivalent. Thus, we might return one ID that is equivelant to others.

class icalendar.prop.vBinary(obj, params: dict[str, str] | None = None)[source]#

Bases: object

Binary property values are base 64 encoded.

static from_ical(ical)[source]#
obj: str#
params: Parameters#
to_ical()[source]#
class icalendar.prop.vBoolean(*args, params: dict[str, Any] | None = None, **kwargs)[source]#

Bases: int

Boolean

Value Name: BOOLEAN

Purpose: This value type is used to identify properties that contain

either a “TRUE” or “FALSE” Boolean value.

Format Definition: This value type is defined by the following

notation:

boolean    = "TRUE" / "FALSE"
Description: These values are case-insensitive text. No additional

content value encoding is defined for this value type.

Example: The following is an example of a hypothetical property that

has a BOOLEAN value type:

TRUE

>>> from icalendar.prop import vBoolean
>>> boolean = vBoolean.from_ical('TRUE')
>>> boolean
True
>>> boolean = vBoolean.from_ical('FALSE')
>>> boolean
False
>>> boolean = vBoolean.from_ical('True')
>>> boolean
True
BOOL_MAP = {'FALSE': False, 'TRUE': True}#
classmethod from_ical(ical)[source]#
params: Parameters#
to_ical()[source]#
class icalendar.prop.vCalAddress(value, encoding='utf-8', /, params: dict[str, Any] | None = None)[source]#

Bases: str

Calendar User Address

Value Name:

CAL-ADDRESS

Purpose:

This value type is used to identify properties that contain a calendar user address.

Description:

The value is a URI as defined by [RFC3986] or any other IANA-registered form for a URI. When used to address an Internet email transport address for a calendar user, the value MUST be a mailto URI, as defined by [RFC2368].

Example

mailto: is in front of the address.

mailto:jane_doe@example.com

Parsing:

>>> from icalendar import vCalAddress
>>> cal_address = vCalAddress.from_ical('mailto:jane_doe@example.com')
>>> cal_address
vCalAddress('mailto:jane_doe@example.com')

Encoding:

>>> from icalendar import vCalAddress, Event
>>> event = Event()
>>> jane = vCalAddress("mailto:jane_doe@example.com")
>>> jane.name = "Jane"
>>> event["organizer"] = jane
>>> print(event.to_ical().decode().replace('\r\n', '\n').strip())
BEGIN:VEVENT
ORGANIZER;CN=Jane:mailto:jane_doe@example.com
END:VEVENT
property CN: str#

Specify the common name to be associated with the calendar user specified.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the common name to be associated with the calendar user specified by the property. The parameter value is text. The parameter value can be used for display text to be associated with the calendar address specified by the property.

property CUTYPE: CUTYPE | str#

Identify the type of calendar user specified by the property.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter identifies the type of calendar user specified by the property. If not specified on a property that allows this parameter, the default is INDIVIDUAL. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the UNKNOWN value.

property DELEGATED_FROM: tuple[str]#

Specify the calendar users that have delegated their participation to the calendar user specified by the property.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. This parameter specifies those calendar users that have delegated their participation in a group-scheduled event or to-do to the calendar user specified by the property. The individual calendar address parameter values MUST each be specified in a quoted-string.

property DELEGATED_TO: tuple[str]#

Specify the calendar users to whom the calendar user specified by the property has delegated participation.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. This parameter specifies those calendar users whom have been delegated participation in a group-scheduled event or to-do by the calendar user specified by the property. The individual calendar address parameter values MUST each be specified in a quoted-string.

property DIR: str | None#

Specify reference to a directory entry associated with the calendar user specified by the property.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies a reference to the directory entry associated with the calendar user specified by the property. The parameter value is a URI. The URI parameter value MUST be specified in a quoted-string.

Note

While there is no restriction imposed on the URI schemes allowed for this parameter, CID RFC 2392, DATA RFC 2397, FILE RFC 1738, FTP RFC 1738, HTTP RFC 2616, HTTPS RFC 2818, LDAP RFC 4516, and MID RFC 2392 are the URI schemes most commonly used by current implementations.

property LANGUAGE: str | None#

Specify the language for text values in a property or property parameter.

Description:

This parameter identifies the language of the text in the property value and of all property parameter values of the property. The value of the “LANGUAGE” property parameter is that defined in RFC 5646.

For transport in a MIME entity, the Content-Language header field can be used to set the default language for the entire body part. Otherwise, no default language is assumed.

property PARTSTAT: PARTSTAT | str#

Specify the participation status for the calendar user specified by the property.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter identifies the participation status for the calendar user specified by the property value. The parameter values differ depending on whether they are associated with a group-scheduled “VEVENT”, “VTODO”, or “VJOURNAL”. The values MUST match one of the values allowed for the given calendar component. If not specified on a property that allows this parameter, the default value is NEEDS-ACTION. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the NEEDS-ACTION value.

property ROLE: ROLE | str#

Specify the participation role for the calendar user specified by the property.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the participation role for the calendar user specified by the property in the group schedule calendar component. If not specified on a property that allows this parameter, the default value is REQ-PARTICIPANT. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the REQ-PARTICIPANT value.

property RSVP: bool#

Specify whether there is an expectation of a favor of anreply from the calendar user specified by the property value.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter identifies the expectation of a reply from the calendar user specified by the property value. This parameter is used by the “Organizer” to request a participation status reply from an “Attendee” of a group-scheduled event or to-do. If not specified on a property that allows this parameter, the default value is False.

property SENT_BY: str | None#

Specify the calendar user that is acting on behalf of the calendar user specified by the property.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the calendar user that is acting on behalf of the calendar user specified by the property. The parameter value MUST be a mailto URI as defined in RFC 2368. The individual calendar address parameter values MUST each be specified in a quoted-string.

property email: str#

at the start.

Type:

The email address without mailto

classmethod from_ical(ical)[source]#
property name: str#

Specify the common name to be associated with the calendar user specified.

Description:

This parameter can be specified on properties with a CAL-ADDRESS value type. The parameter specifies the common name to be associated with the calendar user specified by the property. The parameter value is text. The parameter value can be used for display text to be associated with the calendar address specified by the property.

classmethod new(email: str, /, cn: str | None = None, cutype: str | None = None, delegated_from: str | None = None, delegated_to: str | None = None, directory: str | None = None, language: str | None = None, partstat: str | None = None, role: str | None = None, rsvp: bool | None = None, sent_by: str | None = None)[source]#

Create a new vCalAddress with RFC 5545 parameters.

Creates a vCalAddress instance with automatic mailto: prefix handling and support for all standard RFC 5545 parameters.

Parameters:

  • email – The email address (mailto: prefix added automatically if missing)

  • cn – Common Name parameter

  • cutype – Calendar user type (INDIVIDUAL, GROUP, RESOURCE, ROOM)

  • delegated_from – Email of the calendar user that delegated

  • delegated_to – Email of the calendar user that was delegated to

  • directory – Reference to directory information

  • language – Language for text values

  • partstat – Participation status (NEEDS-ACTION, ACCEPTED, DECLINED, etc.)

  • role – Role (REQ-PARTICIPANT, OPT-PARTICIPANT, NON-PARTICIPANT, CHAIR)

  • rsvp – Whether RSVP is requested

  • sent_by – Email of the calendar user acting on behalf of this user

Returns:

A new calendar address with specified parameters

Return type:

vCalAddress

Raises:

TypeError – If email is not a string

Examples

Basic usage:

>>> from icalendar.prop import vCalAddress
>>> addr = vCalAddress.new("test@test.com")
>>> str(addr)
'mailto:test@test.com'

With parameters:

>>> addr = vCalAddress.new("test@test.com", cn="Test User", role="CHAIR")
>>> addr.params["CN"]
'Test User'
>>> addr.params["ROLE"]
'CHAIR'
params: Parameters#
to_ical()[source]#
class icalendar.prop.vCategory(c_list: list[str] | str, /, params: dict[str, Any] | None = None)[source]#

Bases: object

static from_ical(ical)[source]#
params: Parameters#
to_ical()[source]#
class icalendar.prop.vDDDLists(dt_list)[source]#

Bases: object

A list of vDDDTypes values.

dts: list#
static from_ical(ical, timezone=None)[source]#
params: Parameters#
to_ical()[source]#
class icalendar.prop.vDDDTypes(dt)[source]#

Bases: TimeBase

A combined Datetime, Date or Duration parser/generator. Their format cannot be confused, and often values can be of either types. So this is practical.

classmethod from_ical(ical, timezone=None)[source]#
params: Parameters#
property td: timedelta#

Compatibility property returning self.dt.

This class is used to replace different time components. Some of them contain a datetime or date (.dt). Some of them contain a timedelta (.td). This property allows interoperability.

to_ical()[source]#
class icalendar.prop.vDate(dt)[source]#

Bases: TimeBase

Date

Value Name:

DATE

Purpose:

This value type is used to identify values that contain a calendar date.

Format Definition:

This value type is defined by the following notation:

date               = date-value

date-value         = date-fullyear date-month date-mday
date-fullyear      = 4DIGIT
date-month         = 2DIGIT        ;01-12
date-mday          = 2DIGIT        ;01-28, 01-29, 01-30, 01-31
                                   ;based on month/year
Description:

If the property permits, multiple “date” values are specified as a COMMA-separated list of values. The format for the value type is based on the [ISO.8601.2004] complete representation, basic format for a calendar date. The textual format specifies a four-digit year, two-digit month, and two-digit day of the month. There are no separator characters between the year, month, and day component text.

Example

The following represents July 14, 1997:

19970714

>>> from icalendar.prop import vDate
>>> date = vDate.from_ical('19970714')
>>> date.year
1997
>>> date.month
7
>>> date.day
14
static from_ical(ical)[source]#
params: Parameters#
to_ical()[source]#
class icalendar.prop.vDatetime(dt, /, params: dict[str, Any] | None = None)[source]#

Bases: TimeBase

Date-Time

Value Name: DATE-TIME

Purpose: This value type is used to identify values that specify a

precise calendar date and time of day. The format is based on the ISO.8601.2004 complete representation.

Format:

YYYYMMDDTHHMMSS

Descripiton: vDatetime is timezone aware and uses a timezone library.

When a vDatetime object is created from an ical string, you can pass a valid timezone identifier. When a vDatetime object is created from a python datetime object, it uses the tzinfo component, if present. Otherwise a timezone-naive object is created. Be aware that there are certain limitations with timezone naive DATE-TIME components in the icalendar standard.

Example 1: The following represents March 2, 2021 at 10:15 with local time:

>>> from icalendar import vDatetime
>>> datetime = vDatetime.from_ical("20210302T101500")
>>> datetime.tzname()
>>> datetime.year
2021
>>> datetime.minute
15

Example 2: The following represents March 2, 2021 at 10:15 in New York:

>>> datetime = vDatetime.from_ical("20210302T101500", 'America/New_York')
>>> datetime.tzname()
'EST'

Example 3: The following represents March 2, 2021 at 10:15 in Berlin:

>>> from zoneinfo import ZoneInfo
>>> timezone = ZoneInfo("Europe/Berlin")
>>> vDatetime.from_ical("20210302T101500", timezone)
datetime.datetime(2021, 3, 2, 10, 15, tzinfo=ZoneInfo(key='Europe/Berlin'))
static from_ical(ical, timezone=None)[source]#

Create a datetime from the RFC string.

params: Parameters#
to_ical()[source]#
class icalendar.prop.vDuration(td, /, params: dict[str, Any] | None = None)[source]#

Bases: TimeBase

Duration

Value Name:

DURATION

Purpose:

This value type is used to identify properties that contain a duration of time.

Format Definition:

This value type is defined by the following notation:

dur-value  = (["+"] / "-") "P" (dur-date / dur-time / dur-week)

dur-date   = dur-day [dur-time]
dur-time   = "T" (dur-hour / dur-minute / dur-second)
dur-week   = 1*DIGIT "W"
dur-hour   = 1*DIGIT "H" [dur-minute]
dur-minute = 1*DIGIT "M" [dur-second]
dur-second = 1*DIGIT "S"
dur-day    = 1*DIGIT "D"
Description:

If the property permits, multiple “duration” values are specified by a COMMA-separated list of values. The format is based on the [ISO.8601.2004] complete representation basic format with designators for the duration of time. The format can represent nominal durations (weeks and days) and accurate durations (hours, minutes, and seconds). Note that unlike [ISO.8601.2004], this value type doesn’t support the “Y” and “M” designators to specify durations in terms of years and months. The duration of a week or a day depends on its position in the calendar. In the case of discontinuities in the time scale, such as the change from standard time to daylight time and back, the computation of the exact duration requires the subtraction or addition of the change of duration of the discontinuity. Leap seconds MUST NOT be considered when computing an exact duration. When computing an exact duration, the greatest order time components MUST be added first, that is, the number of days MUST be added first, followed by the number of hours, number of minutes, and number of seconds.

Example

A duration of 15 days, 5 hours, and 20 seconds would be:

P15DT5H0M20S

A duration of 7 weeks would be:

P7W

>>> from icalendar.prop import vDuration
>>> duration = vDuration.from_ical('P15DT5H0M20S')
>>> duration
datetime.timedelta(days=15, seconds=18020)
>>> duration = vDuration.from_ical('P7W')
>>> duration
datetime.timedelta(days=49)
property dt: timedelta#

The time delta for compatibility.

static from_ical(ical)[source]#
params: Parameters#
to_ical()[source]#
class icalendar.prop.vFloat(*args, params: dict[str, Any] | None = None, **kwargs)[source]#

Bases: float

Float

Value Name:

FLOAT

Purpose:

This value type is used to identify properties that contain a real-number value.

Format Definition:

This value type is defined by the following notation:

float      = (["+"] / "-") 1*DIGIT ["." 1*DIGIT]
Description:

If the property permits, multiple “float” values are specified by a COMMA-separated list of values.

Example:

1000000.0000001
1.333
-3.14

>>> from icalendar.prop import vFloat
>>> float = vFloat.from_ical('1000000.0000001')
>>> float
1000000.0000001
>>> float = vFloat.from_ical('1.333')
>>> float
1.333
>>> float = vFloat.from_ical('+1.333')
>>> float
1.333
>>> float = vFloat.from_ical('-3.14')
>>> float
-3.14
classmethod from_ical(ical)[source]#
params: Parameters#
to_ical()[source]#
class icalendar.prop.vFrequency(value, encoding='utf-8', /, params: dict[str, Any] | None = None)[source]#

Bases: str

A simple class that catches illegal values.

frequencies = {'DAILY': 'DAILY', 'HOURLY': 'HOURLY', 'MINUTELY': 'MINUTELY', 'MONTHLY': 'MONTHLY', 'SECONDLY': 'SECONDLY', 'WEEKLY': 'WEEKLY', 'YEARLY': 'YEARLY'}#
classmethod from_ical(ical)[source]#
params: Parameters#
to_ical()[source]#
class icalendar.prop.vGeo(geo: tuple[float | str | int, float | str | int], /, params: dict[str, Any] | None = None)[source]#

Bases: object

Geographic Position

Property Name:

GEO

Purpose:

This property specifies information related to the global position for the activity specified by a calendar component.

Value Type:

FLOAT. The value MUST be two SEMICOLON-separated FLOAT values.

Property Parameters:

IANA and non-standard property parameters can be specified on this property.

Conformance:

This property can be specified in “VEVENT” or “VTODO” calendar components.

Description:

This property value specifies latitude and longitude, in that order (i.e., “LAT LON” ordering). The longitude represents the location east or west of the prime meridian as a positive or negative real number, respectively. The longitude and latitude values MAY be specified up to six decimal places, which will allow for accuracy to within one meter of geographical position. Receiving applications MUST accept values of this precision and MAY truncate values of greater precision.

Example:

GEO:37.386013;-122.082932

Parse vGeo:

>>> from icalendar.prop import vGeo
>>> geo = vGeo.from_ical('37.386013;-122.082932')
>>> geo
(37.386013, -122.082932)

Add a geo location to an event:

>>> from icalendar import Event
>>> event = Event()
>>> latitude = 37.386013
>>> longitude = -122.082932
>>> event.add('GEO', (latitude, longitude))
>>> event['GEO']
vGeo((37.386013, -122.082932))
static from_ical(ical)[source]#
params: Parameters#

Create a new vGeo from a tuple of (latitude, longitude).

Raises:

ValueError – if geo is not a tuple of (latitude, longitude)

to_ical()[source]#
class icalendar.prop.vInline(value, encoding='utf-8', /, params: dict[str, Any] | None = None)[source]#

Bases: str

This is an especially dumb class that just holds raw unparsed text and has parameters. Conversion of inline values are handled by the Component class, so no further processing is needed.

classmethod from_ical(ical)[source]#
params: Parameters#
to_ical()[source]#
class icalendar.prop.vInt(*args, params: dict[str, Any] | None = None, **kwargs)[source]#

Bases: int

Integer

Value Name:

INTEGER

Purpose:

This value type is used to identify properties that contain a signed integer value.

Format Definition:

This value type is defined by the following notation:

integer    = (["+"] / "-") 1*DIGIT
Description:

If the property permits, multiple “integer” values are specified by a COMMA-separated list of values. The valid range for “integer” is -2147483648 to 2147483647. If the sign is not specified, then the value is assumed to be positive.

Example:

1234567890
-1234567890
+1234567890
432109876

>>> from icalendar.prop import vInt
>>> integer = vInt.from_ical('1234567890')
>>> integer
1234567890
>>> integer = vInt.from_ical('-1234567890')
>>> integer
-1234567890
>>> integer = vInt.from_ical('+1234567890')
>>> integer
1234567890
>>> integer = vInt.from_ical('432109876')
>>> integer
432109876
classmethod from_ical(ical: str | bytes)[source]#
params: Parameters#
to_ical() → bytes[source]#
class icalendar.prop.vMonth(month: str | int, /, params: dict[str, Any] | None = None)[source]#

Bases: int

The number of the month for recurrence.

In RFC 5545, this is just an int. In RFC 7529, this can be followed by L to indicate a leap month.

>>> from icalendar import vMonth
>>> vMonth(1) # first month January
vMonth('1')
>>> vMonth("5L") # leap month in Hebrew calendar
vMonth('5L')
>>> vMonth(1).leap
False
>>> vMonth("5L").leap
True

Definition from RFC:

type-bymonth = element bymonth {
   xsd:positiveInteger |
   xsd:string
}
classmethod from_ical(ical: str)[source]#
property leap: bool#

Whether this is a leap month.

params: Parameters#
to_ical() → bytes[source]#

The ical representation.

class icalendar.prop.vPeriod(per: tuple[datetime, datetime | timedelta])[source]#

Bases: TimeBase

Period of Time

Value Name:

PERIOD

Purpose:

This value type is used to identify values that contain a precise period of time.

Format Definition:

This value type is defined by the following notation:

 period     = period-explicit / period-start

period-explicit = date-time "/" date-time
; [ISO.8601.2004] complete representation basic format for a
; period of time consisting of a start and end.  The start MUST
; be before the end.

period-start = date-time "/" dur-value
; [ISO.8601.2004] complete representation basic format for a
; period of time consisting of a start and positive duration
; of time.
Description:

If the property permits, multiple “period” values are specified by a COMMA-separated list of values. There are two forms of a period of time. First, a period of time is identified by its start and its end. This format is based on the [ISO.8601.2004] complete representation, basic format for “DATE- TIME” start of the period, followed by a SOLIDUS character followed by the “DATE-TIME” of the end of the period. The start of the period MUST be before the end of the period. Second, a period of time can also be defined by a start and a positive duration of time. The format is based on the [ISO.8601.2004] complete representation, basic format for the “DATE-TIME” start of the period, followed by a SOLIDUS character, followed by the [ISO.8601.2004] basic format for “DURATION” of the period.

Example

The period starting at 18:00:00 UTC, on January 1, 1997 and ending at 07:00:00 UTC on January 2, 1997 would be:

19970101T180000Z/19970102T070000Z

The period start at 18:00:00 on January 1, 1997 and lasting 5 hours and 30 minutes would be:

19970101T180000Z/PT5H30M

>>> from icalendar.prop import vPeriod
>>> period = vPeriod.from_ical('19970101T180000Z/19970102T070000Z')
>>> period = vPeriod.from_ical('19970101T180000Z/PT5H30M')
property FBTYPE: FBTYPE | str#

Specify the free or busy time type.

Description:

This parameter specifies the free or busy time type. The value FREE indicates that the time interval is free for scheduling. The value BUSY indicates that the time interval is busy because one or more events have been scheduled for that interval. The value BUSY-UNAVAILABLE indicates that the time interval is busy and that the interval can not be scheduled. The value BUSY-TENTATIVE indicates that the time interval is busy because one or more events have been tentatively scheduled for that interval. If not specified on a property that allows this parameter, the default is BUSY. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the BUSY value.

property dt#

Make this cooperate with the other vDDDTypes.

static from_ical(ical, timezone=None)[source]#
overlaps(other)[source]#
params: Parameters#
to_ical()[source]#
class icalendar.prop.vRecur(*args, params: dict[str, Any] | None = None, **kwargs)[source]#

Bases: CaselessDict

Recurrence definition.

Property Name:

RRULE

Purpose:

This property defines a rule or repeating pattern for recurring events, to-dos, journal entries, or time zone definitions.

Value Type:

RECUR

Property Parameters:

IANA and non-standard 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, but it SHOULD NOT be specified more than once. The recurrence set generated with multiple “RRULE” properties is undefined.

Description:

The recurrence rule, if specified, is 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 be synchronized with the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value not synchronized with the recurrence 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.

The “DTSTART” property specified within the iCalendar object defines the first instance of the recurrence. In most cases, a “DTSTART” property of DATE-TIME value type used with a recurrence rule, should be specified as a date with local time and time zone reference to make sure all the recurrence instances start at the same local time regardless of time zone changes.

If the duration of the recurring component is specified with the “DTEND” or “DUE” property, then the same exact duration will apply to all the members of the generated recurrence set. Else, if the duration of the recurring component is specified with the “DURATION” property, then the same nominal duration will apply to all the members of the generated recurrence set and the exact duration of each recurrence instance will depend on its specific start time. For example, recurrence instances of a nominal duration of one day will have an exact duration of more or less than 24 hours on a day where a time zone shift occurs. The duration of a specific recurrence may be modified in an exception component or simply by using an “RDATE” property of PERIOD value type.

Examples

The following RRULE specifies daily events for 10 occurrences.

RRULE:FREQ=DAILY;COUNT=10

Below, we parse the RRULE ical string.

>>> from icalendar.prop import vRecur
>>> rrule = vRecur.from_ical('FREQ=DAILY;COUNT=10')
>>> rrule
vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})

You can choose to add an rrule to an icalendar.cal.Event or icalendar.cal.Todo.

>>> from icalendar import Event
>>> event = Event()
>>> event.add('RRULE', 'FREQ=DAILY;COUNT=10')
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]
canonical_order = ('RSCALE', 'FREQ', 'UNTIL', 'COUNT', 'INTERVAL', 'BYSECOND', 'BYMINUTE', 'BYHOUR', 'BYDAY', 'BYWEEKDAY', 'BYMONTHDAY', 'BYYEARDAY', 'BYWEEKNO', 'BYMONTH', 'BYSETPOS', 'WKST', 'SKIP')#
frequencies = ['SECONDLY', 'MINUTELY', 'HOURLY', 'DAILY', 'WEEKLY', 'MONTHLY', 'YEARLY']#
classmethod from_ical(ical: str)[source]#
params: Parameters#
classmethod parse_type(key, values)[source]#
to_ical()[source]#
types = {'BYDAY': <class 'icalendar.prop.vWeekday'>, 'BYHOUR': <class 'icalendar.prop.vInt'>, 'BYMINUTE': <class 'icalendar.prop.vInt'>, 'BYMONTH': <class 'icalendar.prop.vMonth'>, 'BYMONTHDAY': <class 'icalendar.prop.vInt'>, 'BYSECOND': <class 'icalendar.prop.vInt'>, 'BYSETPOS': <class 'icalendar.prop.vInt'>, 'BYWEEKDAY': <class 'icalendar.prop.vWeekday'>, 'BYWEEKNO': <class 'icalendar.prop.vInt'>, 'BYYEARDAY': <class 'icalendar.prop.vInt'>, 'COUNT': <class 'icalendar.prop.vInt'>, 'FREQ': <class 'icalendar.prop.vFrequency'>, 'INTERVAL': <class 'icalendar.prop.vInt'>, 'SKIP': <enum 'vSkip'>, 'UNTIL': <class 'icalendar.prop.vDDDTypes'>, 'WKST': <class 'icalendar.prop.vWeekday'>}#
class icalendar.prop.vSkip(*values)[source]#

Bases: vText, Enum

Skip values for RRULE.

These are defined in RFC 7529.

OMIT is the default value.

Examples:

>>> from icalendar import vSkip
>>> vSkip.OMIT
vSkip('OMIT')
>>> vSkip.FORWARD
vSkip('FORWARD')
>>> vSkip.BACKWARD
vSkip('BACKWARD')
BACKWARD = vText(b'BACKWARD')#
FORWARD = vText(b'FORWARD')#
OMIT = vText(b'OMIT')#
encoding#
params: Parameters#
class icalendar.prop.vText(value, encoding='utf-8', /, params: dict[str, Any] | None = None)[source]#

Bases: str

Simple text.

property ALTREP: str | None#

ALTREP - Specify an alternate text representation for the property value.

Description:

This parameter specifies a URI that points to an alternate representation for a textual property value. A property specifying this parameter MUST also include a value that reflects the default representation of the text value. The URI parameter value MUST be specified in a quoted-string.

Note

While there is no restriction imposed on the URI schemes allowed for this parameter, Content Identifier (CID) RFC 2392, HTTP RFC 2616, and HTTPS RFC 2818 are the URI schemes most commonly used by current implementations.

property LANGUAGE: str | None#

Specify the language for text values in a property or property parameter.

Description:

This parameter identifies the language of the text in the property value and of all property parameter values of the property. The value of the “LANGUAGE” property parameter is that defined in RFC 5646.

For transport in a MIME entity, the Content-Language header field can be used to set the default language for the entire body part. Otherwise, no default language is assumed.

property RELTYPE: RELTYPE#

Specify the type of hierarchical relationship associated with a component.

Description:

This parameter can be specified on a property that references another related calendar. The parameter specifies the hierarchical relationship type of the calendar component referenced by the property. The parameter value can be PARENT, to indicate that the referenced calendar component is a superior of calendar component; CHILD to indicate that the referenced calendar component is a subordinate of the calendar component; or SIBLING to indicate that the referenced calendar component is a peer of the calendar component. If this parameter is not specified on an allowable property, the default relationship type is PARENT. Applications MUST treat x-name and iana-token values they don’t recognize the same way as they would the PARENT value.

encoding#
classmethod from_ical(ical: str | bytes)[source]#
params: Parameters#
to_ical() → bytes[source]#
class icalendar.prop.vTime(*args)[source]#

Bases: TimeBase

Time

Value Name:

TIME

Purpose:

This value type is used to identify values that contain a time of day.

Format Definition:

This value type is defined by the following notation:

time         = time-hour time-minute time-second [time-utc]

time-hour    = 2DIGIT        ;00-23
time-minute  = 2DIGIT        ;00-59
time-second  = 2DIGIT        ;00-60
;The "60" value is used to account for positive "leap" seconds.

time-utc     = "Z"
Description:

If the property permits, multiple “time” values are specified by a COMMA-separated list of values. No additional content value encoding (i.e., BACKSLASH character encoding, see vText) is defined for this value type.

The “TIME” value type is used to identify values that contain a time of day. The format is based on the [ISO.8601.2004] complete representation, basic format for a time of day. The text format consists of a two-digit, 24-hour of the day (i.e., values 00-23), two-digit minute in the hour (i.e., values 00-59), and two-digit seconds in the minute (i.e., values 00-60). The seconds value of 60 MUST only be used to account for positive “leap” seconds. Fractions of a second are not supported by this format.

In parallel to the “DATE-TIME” definition above, the “TIME” value type expresses time values in three forms:

The form of time with UTC offset MUST NOT be used. For example, the following is not valid for a time value:

230000-0800        ;Invalid time format

FORM #1 LOCAL TIME

The local time form is simply a time value that does not contain the UTC designator nor does it reference a time zone. For example, 11:00 PM:

230000

Time values of this type are said to be “floating” and are not bound to any time zone in particular. They are used to represent the same hour, minute, and second value regardless of which time zone is currently being observed. For example, an event can be defined that indicates that an individual will be busy from 11:00 AM to 1:00 PM every day, no matter which time zone the person is in. In these cases, a local time can be specified. The recipient of an iCalendar object with a property value consisting of a local time, without any relative time zone information, SHOULD interpret the value as being fixed to whatever time zone the “ATTENDEE” is in at any given moment. This means that two “Attendees”, may participate in the same event at different UTC times; floating time SHOULD only be used where that is reasonable behavior.

In most cases, a fixed time is desired. To properly communicate a fixed time in a property value, either UTC time or local time with time zone reference MUST be specified.

The use of local time in a TIME value without the “TZID” property parameter is to be interpreted as floating time, regardless of the existence of “VTIMEZONE” calendar components in the iCalendar object.

FORM #2: UTC TIME

UTC time, or absolute time, is identified by a LATIN CAPITAL LETTER Z suffix character, the UTC designator, appended to the time value. For example, the following represents 07:00 AM UTC:

070000Z

The “TZID” property parameter MUST NOT be applied to TIME properties whose time values are specified in UTC.

FORM #3: LOCAL TIME AND TIME ZONE REFERENCE

The local time with reference to time zone information form is identified by the use the “TZID” property parameter to reference the appropriate time zone definition.

Example:

The following represents 8:30 AM in New York in winter, five hours behind UTC, in each of the three formats:

083000
133000Z
TZID=America/New_York:083000
static from_ical(ical)[source]#
to_ical()[source]#
class icalendar.prop.vUTCOffset(td, /, params: dict[str, Any] | None = None)[source]#

Bases: object

UTC Offset

Value Name:

UTC-OFFSET

Purpose:

This value type is used to identify properties that contain an offset from UTC to local time.

Format Definition:

This value type is defined by the following notation:

utc-offset = time-numzone

time-numzone = ("+" / "-") time-hour time-minute [time-second]
Description:

The PLUS SIGN character MUST be specified for positive UTC offsets (i.e., ahead of UTC). The HYPHEN-MINUS character MUST be specified for negative UTC offsets (i.e., behind of UTC). The value of “-0000” and “-000000” are not allowed. The time-second, if present, MUST NOT be 60; if absent, it defaults to zero.

Example:

The following UTC offsets are given for standard time for New York (five hours behind UTC) and Geneva (one hour ahead of UTC):

-0500

+0100

>>> from icalendar.prop import vUTCOffset
>>> utc_offset = vUTCOffset.from_ical('-0500')
>>> utc_offset
datetime.timedelta(days=-1, seconds=68400)
>>> utc_offset = vUTCOffset.from_ical('+0100')
>>> utc_offset
datetime.timedelta(seconds=3600)
classmethod from_ical(ical)[source]#
ignore_exceptions = False#
params: Parameters#
to_ical()[source]#
class icalendar.prop.vUri(value: str, encoding: str = 'utf-8', /, params: dict[str, Any] | None = None)[source]#

Bases: str

URI

Value Name:

URI

Purpose:

This value type is used to identify values that contain a uniform resource identifier (URI) type of reference to the property value.

Format Definition:

This value type is defined by the following notation:

uri = scheme ":" hier-part [ "?" query ] [ "#" fragment ]
Description:

This value type might be used to reference binary information, for values that are large, or otherwise undesirable to include directly in the iCalendar object.

Property values with this value type MUST follow the generic URI syntax defined in [RFC3986].

When a property parameter value is a URI value type, the URI MUST be specified as a quoted-string value.

Example:

The following is a URI for a network file:

http://example.com/my-report.txt

>>> from icalendar.prop import vUri
>>> uri = vUri.from_ical('http://example.com/my-report.txt')
>>> uri
'http://example.com/my-report.txt'
classmethod from_ical(ical)[source]#
params: Parameters#
to_ical()[source]#
class icalendar.prop.vWeekday(value, encoding='utf-8', /, params: dict[str, Any] | None = None)[source]#

Bases: str

Either a weekday or a weekdaynum

>>> from icalendar import vWeekday
>>> vWeekday("MO") # Simple weekday
'MO'
>>> vWeekday("2FR").relative # Second friday
2
>>> vWeekday("2FR").weekday
'FR'
>>> vWeekday("-1SU").relative # Last Sunday
-1

Definition from RFC 5545, Section 3.3.10:

weekdaynum = [[plus / minus] ordwk] weekday
plus        = "+"
minus       = "-"
ordwk       = 1*2DIGIT       ;1 to 53
weekday     = "SU" / "MO" / "TU" / "WE" / "TH" / "FR" / "SA"
;Corresponding to SUNDAY, MONDAY, TUESDAY, WEDNESDAY, THURSDAY,
;FRIDAY, and SATURDAY days of the week.
classmethod from_ical(ical)[source]#
params: Parameters#
relative#
to_ical()[source]#
week_days = {'FR': 5, 'MO': 1, 'SA': 6, 'SU': 0, 'TH': 4, 'TU': 2, 'WE': 3}#
weekday#

Submodules#

On this page
Edit on GitHub

This Page