icalendar.cal.timezone module

RFC 5545 components for timezone information.

class icalendar.cal.timezone.Timezone(*args, **kwargs)

Bases: Component

A “VTIMEZONE” calendar component is a grouping of component properties that defines a time zone. It is used to describe the way in which a time zone changes its offset from UTC over time.

DEFAULT_FIRST_DATE = datetime.date(1970, 1, 1)

DEFAULT_LAST_DATE = datetime.date(2038, 1, 1)

canonical_order = ('TZID',)

property daylight: list[TimezoneDaylight]

The DAYLIGHT subcomponents as a list.

These are for the daylight saving time.

classmethod example(name: str = 'pacific_fiji') → Calendar

Return the timezone example with the given name.

classmethod from_tzid(tzid: str, tzp: TZP = TZP('zoneinfo'), first_date: date = datetime.date(1970, 1, 1), last_date: date = datetime.date(2038, 1, 1)) → Timezone

Create a VTIMEZONE from a tzid like "Europe/Berlin".

Parameters:

• tzid – the id of the timezone

• tzp – the timezone provider

• first_date – a datetime that is earlier than anything that happens in the calendar

• last_date – a datetime that is later than anything that happens in the calendar

Raises:

ValueError – If the tzid is unknown.

>>> from icalendar import Timezone
>>> tz = Timezone.from_tzid("Europe/Berlin")
>>> print(tz.to_ical()[:36])
BEGIN:VTIMEZONE
TZID:Europe/Berlin

Note

This can take some time. Please cache the results.

classmethod from_tzinfo(timezone: tzinfo, tzid: str | None = None, first_date: date = datetime.date(1970, 1, 1), last_date: date = datetime.date(2038, 1, 1)) → Timezone

Return a VTIMEZONE component from a timezone object.

This works with pytz and zoneinfo and any other timezone. The offsets are calculated from the tzinfo object.

Parameters:

Parameters:

• tzinfo – the timezone object

• tzid – the tzid for this timezone. If None, it will be extracted from the tzinfo.

• first_date – a datetime that is earlier than anything that happens in the calendar

• last_date – a datetime that is later than anything that happens in the calendar

Raises:

ValueError – If we have no tzid and cannot extract one.

Note

This can take some time. Please cache the results.

get_transitions() → tuple[list[datetime], list[tuple[timedelta, timedelta, str]]]

Return a tuple of (transition_times, transition_info)

• transition_times = [datetime, …]

• transition_info = [(TZOFFSETTO, dts_offset, tzname)]

name = 'VTIMEZONE'

required = ('TZID',)

singletons = ('TZID', 'LAST-MODIFIED', 'TZURL')

property standard: list[TimezoneStandard]

The STANDARD subcomponents as a list.

subcomponents: list[TimezoneStandard | TimezoneDaylight]

to_tz(tzp: TZP = TZP('zoneinfo'), lookup_tzid: bool = True)

convert this VTIMEZONE component to a timezone object

Parameters:

• tzp – timezone provider to use

• lookup_tzid – whether to use the TZID property to look up existing timezone definitions with tzp. If it is False, a new timezone will be created. If it is True, the existing timezone will be used if it exists, otherwise a new timezone will be created.

property tz_name: str

Return the name of the timezone component.

Please note that the names of the timezone are different from this name and may change with winter/summer time.

class icalendar.cal.timezone.TimezoneDaylight(*args, **kwargs)

Bases: Component

The “DAYLIGHT” sub-component of “VTIMEZONE” defines the daylight saving time offset from UTC for a time zone. It represents a time zone’s daylight saving time, typically used during summer months in locations that observe Daylight Saving Time.

property DTSTART: datetime | None

The DTSTART property.

The mandatory “DTSTART” property gives the effective onset date

and local time for the time zone sub-component definition. “DTSTART” in this usage MUST be specified as a date with a local time value.

Accepted values: datetime. 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 TZOFFSETFROM: timedelta | None

The TZOFFSETFROM property.

The mandatory “TZOFFSETFROM” property gives the UTC offset that is

in use when the onset of this time zone observance begins. “TZOFFSETFROM” is combined with “DTSTART” to define the effective onset for the time zone sub-component definition. For example, the following represents the time at which the observance of Standard Time took effect in Fall 1967 for New York City:

DTSTART:19671029T020000 TZOFFSETFROM:-0400

Accepted values: timedelta. 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 TZOFFSETTO: timedelta | None

The TZOFFSETTO property.

The mandatory “TZOFFSETTO” property gives the UTC offset for the

time zone sub-component (Standard Time or Daylight Saving Time) when this observance is in use.

Accepted values: timedelta. 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 exdates: list[date | datetime]

EXDATE defines the list of DATE-TIME exceptions for recurring components.

EXDATE is defined in RFC 5545.

Value Type:

The default value type for this property is DATE-TIME. The value type can be set to DATE.

Property Parameters:

IANA, non-standard, value data type, and time zone identifier 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.

Description:

The exception dates, if specified, are 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 match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the 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”). When duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

The “EXDATE” property can be used to exclude the value specified in “DTSTART”. However, in such cases, the original “DTSTART” date MUST still be maintained by the calendaring and scheduling system because the original “DTSTART” value has inherent usage dependencies by other properties such as the “RECURRENCE-ID”.

Example

Below, we add an exdate in a list and get the resulting list of exdates.

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event()

# Add a list of excluded dates
>>> event.add("EXDATE", [datetime(2025, 4, 28, 16, 5)])
>>> event.exdates
[datetime.datetime(2025, 4, 28, 16, 5)]

Note

You cannot modify the EXDATE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related projects.

multiple = ('COMMENT', 'RDATE', 'TZNAME', 'RRULE', 'EXDATE')

name = 'DAYLIGHT'

property rdates: list[tuple[date, None] | tuple[datetime, None] | tuple[datetime, datetime]]

The RDATE property defines the list of DATE-TIME values for recurring components.

RDATE is defined in RFC 5545. The return value is a list of tuples (start, end).

start can be a datetime.date or a datetime.datetime, with and without timezone.

end is None if the end is not specified and a datetime.datetime if the end is specified.

Value Type:

The default value type for this property is DATE-TIME. The value type can be set to DATE or PERIOD.

Property Parameters:

IANA, non-standard, value data type, and time zone identifier 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.

Description:

This property can appear along with the “RRULE” property to define an aggregate set of repeating occurrences. When they both appear in a recurring component, the recurrence instances are defined by the union of occurrences defined by both the “RDATE” and “RRULE”.

The recurrence dates, if specified, are 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 match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the 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.

Example

Below, we set one RDATE in a list and get the resulting tuple of start and end.

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event()

# Add a list of recurrence dates
>>> event.add("RDATE", [datetime(2025, 4, 28, 16, 5)])
>>> event.rdates
[(datetime.datetime(2025, 4, 28, 16, 5), None)]

Note

You cannot modify the RDATE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related projects.

required = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM')

property rrules: list[vRecur]

RRULE defines a rule or repeating pattern for recurring components.

RRULE is defined in RFC 5545. RFC 7529 adds the SKIP parameter icalendar.prop.vSkip.

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

Daily for 10 occurrences:

>>> from icalendar import Event
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> event = Event()
>>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
>>> event.add("RRULE", "FREQ=DAILY;COUNT=10")
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;COUNT=10
END:VEVENT
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]

Daily until December 24, 1997:

>>> from icalendar import Event, vRecur
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> event = Event()
>>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
>>> event.add("RRULE", vRecur({"FREQ": ["DAILY"]}, until=datetime(1997, 12, 24, tzinfo=ZoneInfo("UTC"))))
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;UNTIL=19971224T000000Z
END:VEVENT
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'UNTIL': [datetime.datetime(1997, 12, 24, 0, 0, tzinfo=ZoneInfo(key='UTC'))]})]

Note

You cannot modify the RRULE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related projects.

singletons = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM')

subcomponents: list[Component]

class icalendar.cal.timezone.TimezoneStandard(*args, **kwargs)

Bases: Component

The “STANDARD” sub-component of “VTIMEZONE” defines the standard time offset from UTC for a time zone. It represents a time zone’s standard time, typically used during winter months in locations that observe Daylight Saving Time.

property DTSTART: datetime | None

The DTSTART property.

The mandatory “DTSTART” property gives the effective onset date

and local time for the time zone sub-component definition. “DTSTART” in this usage MUST be specified as a date with a local time value.

Accepted values: datetime. 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 TZOFFSETFROM: timedelta | None

The TZOFFSETFROM property.

The mandatory “TZOFFSETFROM” property gives the UTC offset that is

in use when the onset of this time zone observance begins. “TZOFFSETFROM” is combined with “DTSTART” to define the effective onset for the time zone sub-component definition. For example, the following represents the time at which the observance of Standard Time took effect in Fall 1967 for New York City:

DTSTART:19671029T020000 TZOFFSETFROM:-0400

Accepted values: timedelta. 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 TZOFFSETTO: timedelta | None

The TZOFFSETTO property.

The mandatory “TZOFFSETTO” property gives the UTC offset for the

time zone sub-component (Standard Time or Daylight Saving Time) when this observance is in use.

Accepted values: timedelta. 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 exdates: list[date | datetime]

EXDATE defines the list of DATE-TIME exceptions for recurring components.

EXDATE is defined in RFC 5545.

Value Type:

The default value type for this property is DATE-TIME. The value type can be set to DATE.

Property Parameters:

IANA, non-standard, value data type, and time zone identifier 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.

Description:

The exception dates, if specified, are 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 match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the 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”). When duplicate instances are generated by the “RRULE” and “RDATE” properties, only one recurrence is considered. Duplicate instances are ignored.

The “EXDATE” property can be used to exclude the value specified in “DTSTART”. However, in such cases, the original “DTSTART” date MUST still be maintained by the calendaring and scheduling system because the original “DTSTART” value has inherent usage dependencies by other properties such as the “RECURRENCE-ID”.

Example

Below, we add an exdate in a list and get the resulting list of exdates.

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event()

# Add a list of excluded dates
>>> event.add("EXDATE", [datetime(2025, 4, 28, 16, 5)])
>>> event.exdates
[datetime.datetime(2025, 4, 28, 16, 5)]

Note

You cannot modify the EXDATE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related projects.

multiple = ('COMMENT', 'RDATE', 'TZNAME', 'RRULE', 'EXDATE')

name = 'STANDARD'

property rdates: list[tuple[date, None] | tuple[datetime, None] | tuple[datetime, datetime]]

The RDATE property defines the list of DATE-TIME values for recurring components.

RDATE is defined in RFC 5545. The return value is a list of tuples (start, end).

start can be a datetime.date or a datetime.datetime, with and without timezone.

end is None if the end is not specified and a datetime.datetime if the end is specified.

Value Type:

The default value type for this property is DATE-TIME. The value type can be set to DATE or PERIOD.

Property Parameters:

IANA, non-standard, value data type, and time zone identifier 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.

Description:

This property can appear along with the “RRULE” property to define an aggregate set of repeating occurrences. When they both appear in a recurring component, the recurrence instances are defined by the union of occurrences defined by both the “RDATE” and “RRULE”.

The recurrence dates, if specified, are 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 match the pattern of the recurrence rule, if specified. The recurrence set generated with a “DTSTART” property value that doesn’t match the pattern of the 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.

Example

Below, we set one RDATE in a list and get the resulting tuple of start and end.

>>> from icalendar import Event
>>> from datetime import datetime
>>> event = Event()

# Add a list of recurrence dates
>>> event.add("RDATE", [datetime(2025, 4, 28, 16, 5)])
>>> event.rdates
[(datetime.datetime(2025, 4, 28, 16, 5), None)]

Note

You cannot modify the RDATE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related projects.

required = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM')

property rrules: list[vRecur]

RRULE defines a rule or repeating pattern for recurring components.

RRULE is defined in RFC 5545. RFC 7529 adds the SKIP parameter icalendar.prop.vSkip.

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

Daily for 10 occurrences:

>>> from icalendar import Event
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> event = Event()
>>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
>>> event.add("RRULE", "FREQ=DAILY;COUNT=10")
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;COUNT=10
END:VEVENT
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'COUNT': [10]})]

Daily until December 24, 1997:

>>> from icalendar import Event, vRecur
>>> from datetime import datetime
>>> from zoneinfo import ZoneInfo
>>> event = Event()
>>> event.start = datetime(1997, 9, 2, 9, 0, tzinfo=ZoneInfo("America/New_York"))
>>> event.add("RRULE", vRecur({"FREQ": ["DAILY"]}, until=datetime(1997, 12, 24, tzinfo=ZoneInfo("UTC"))))
>>> print(event.to_ical())
BEGIN:VEVENT
DTSTART;TZID=America/New_York:19970902T090000
RRULE:FREQ=DAILY;UNTIL=19971224T000000Z
END:VEVENT
>>> event.rrules
[vRecur({'FREQ': ['DAILY'], 'UNTIL': [datetime.datetime(1997, 12, 24, 0, 0, tzinfo=ZoneInfo(key='UTC'))]})]

Note

You cannot modify the RRULE value by modifying the result. Use icalendar.cal.Component.add() to add values.

If you want to compute recurrences, have a look at Related projects.

singletons = ('DTSTART', 'TZOFFSETTO', 'TZOFFSETFROM')

subcomponents: list[Component]