Skip to content

Documentation for your first returned item: VCalendar

Once you imported the iCal-library library, you can use either the client or CacheCLient to get a VCalendar object. This page explains all the functions and attributes of the VCalendar object.

VCalendar

Bases: Component

This class represents the VCALENDAR component specified in RFC 5545 in '3.6. Calendar Components'.

The "VCALENDAR" component consists of a sequence of calendar properties and one or more calendar components. The calendar properties are attributes that apply to the calendar object as a whole. The calendar components are collections of properties that express a particular calendar semantic. For example, the calendar component can specify an event, a to-do, a journal entry, time zone information, free/busy time information, or an alarm.

Parameters:

Name Type Description Default
prodid Optional[ProdID]

The ProdID property. Required and must occur exactly once.

 None
version Optional[Version]

The Version property. Required and must occur exactly once.

 None
calscale Optional[CalScale]

The CalScale property. Optional, but may occur at most once.

 None
method Optional[Method]

The Method property. Optional, but may occur at most once.

 None
events Optional[List[VEvent]]

Optional list of VEvent components. Each component may occur multiple times.

 None
todos Optional[List[VToDo]]

Optional list of VToDo components. Each component may occur multiple times.

 None
journals Optional[List[VJournal]]

Optional list of VJournal components. Each component may occur multiple times.

 None
free_busy_list Optional[List[VFreeBusy]]

Optional list of VFreeBusy components. Each component may occur multiple times.

 None
time_zones Optional[List[VTimeZone]]

Optional list of VTimeZone components. Each component may occur multiple times.

 None
Source code in ical_library/ical_components/v_calendar.py 
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
class VCalendar(Component):
    """
    This class represents the VCALENDAR component specified in RFC 5545 in '3.6. Calendar Components'.

    The "VCALENDAR" component consists of a sequence of calendar properties and one or more calendar components.
    The calendar properties are attributes that apply to the calendar object as a whole. The calendar components are
    collections of properties that express a particular calendar semantic. For example, the calendar component can
    specify an event, a to-do, a journal entry, time zone information, free/busy time information, or an alarm.

    :param prodid: The ProdID property. Required and must occur exactly once.
    :param version: The Version property. Required and must occur exactly once.
    :param calscale: The CalScale property. Optional, but may occur at most once.
    :param method: The Method property. Optional, but may occur at most once.
    :param events: Optional list of VEvent components. Each component may occur multiple times.
    :param todos: Optional list of VToDo components. Each component may occur multiple times.
    :param journals: Optional list of VJournal components. Each component may occur multiple times.
    :param free_busy_list: Optional list of VFreeBusy components. Each component may occur multiple times.
    :param time_zones: Optional list of VTimeZone components. Each component may occur multiple times.
    """

    def __init__(
        self,
        prodid: Optional[ProdID] = None,
        version: Optional[Version] = None,
        calscale: Optional[CalScale] = None,
        method: Optional[Method] = None,
        events: Optional[List[VEvent]] = None,
        todos: Optional[List[VToDo]] = None,
        journals: Optional[List[VJournal]] = None,
        free_busy_list: Optional[List[VFreeBusy]] = None,
        time_zones: Optional[List[VTimeZone]] = None,
    ):
        super().__init__("VCALENDAR")

        # Required properties, only one occurrence allowed.
        self._prodid: Optional[ProdID] = self.as_parent(prodid)
        self._version: Optional[Version] = self.as_parent(version)

        # Optional properties, must not occur more than once.
        self.calscale: Optional[CalScale] = self.as_parent(calscale)
        self.method: Optional[Method] = self.as_parent(method)

        # These are children Components
        self.events: List[VEvent] = events or []
        self.todos: List[VToDo] = todos or []
        self.journals: List[VJournal] = journals or []
        self.free_busy_list: List[VFreeBusy] = free_busy_list or []
        self.time_zones: List[VTimeZone] = time_zones or []

        # Only the VCalender stores the entire list.
        self._lines: Optional[List[str]] = None

    def __repr__(self) -> str:
        """Overwrite the repr to create a better representation for the item."""
        return f"VCalendar({self.prodid.value}, {self.version.value})"

    @property
    def prodid(self) -> ProdID:
        """A getter to ensure the required property is set."""
        if self._prodid is None:
            raise MissingRequiredProperty(self, "prodid")
        return self._prodid

    @prodid.setter
    def prodid(self, value: ProdID):
        """A setter to set the required property."""
        self._prodid = value

    @property
    def version(self) -> Version:
        """A getter to ensure the required property is set."""
        if self._version is None:
            raise MissingRequiredProperty(self, "version")
        return self._version

    @version.setter
    def version(self, value: Version):
        """A setter to set the required property."""
        self._version = value

    @property
    def calendar_scale(self) -> str:
        """Return the calendar scale according to RFC 5545."""
        return self.calscale.value if self.calscale else "GREGORIAN"

    def get_timezone(self, tzid: str) -> VTimeZone:
        """Get the corresponding VTimeZone object based on the given timezone identifier."""
        for timezone in self.time_zones:
            if timezone.tzid.value == tzid:
                return timezone
        raise ValueError(f"Could not find Timezone with {tzid=}.")

    def get_aware_dt_for_timezone(self, dt: DateTime, tzid: str) -> DateTime:
        """Return the timezone aware DateTime object for a given TimeZone identifier."""
        return self.get_timezone(tzid).convert_naive_datetime_to_aware(dt)

    @property
    def timeline(self) -> "Timeline":
        """Return a timeline of VEvents from 1970-00-00T00:00:00 to 2100-00-00T00:00:00."""
        from ical_library.timeline import Timeline

        return Timeline(self)

    def get_limited_timeline(self, start: Optional[DateTime], end: Optional[DateTime]) -> "Timeline":
        """
        Return a timeline of VEvents limited by *start* and *end*

        :param start: Only include events in the timeline with a starting date later than this value.
        :param end: Only include events in the timeline with a starting date earlier than this value.
        """
        from ical_library.timeline import Timeline

        return Timeline(self, start, end)

    def parse_component(self, lines: List[str], line_number: int) -> int:
        """
        Parse a new component in the RAW string list.
        :param lines: A list of all the lines in the iCalendar file.
        :param line_number: The line number at which this component starts.
        :return: The line number at which this component ends.
        """
        self._lines = lines
        return super().parse_component(lines=lines, line_number=line_number)

    def get_original_ical_text(self, start_line: int, end_line: int) -> str:
        """
        Get the original iCAL text for your property from the RAW string list.
        :param start_line: The starting line index for the component you wish to show.
        :param end_line: The ending line index for the component you wish to show.
        :return: The complete string, as it was in the RAW string list, for the component you wish to show.
        """
        lines = self._lines
        if lines is None:
            raise TypeError("We should first parse the component section before calling this function.")
        return "\n".join(line for line in self.tree_root._lines[max(0, start_line) : min(len(lines), end_line)])

calendar_scale: str property

Return the calendar scale according to RFC 5545.

prodid: ProdID property writable

A getter to ensure the required property is set.

timeline: Timeline property

Return a timeline of VEvents from 1970-00-00T00:00:00 to 2100-00-00T00:00:00.

version: Version property writable

A getter to ensure the required property is set.

get_aware_dt_for_timezone(dt, tzid)

Return the timezone aware DateTime object for a given TimeZone identifier.

Source code in ical_library/ical_components/v_calendar.py 
110
111
112
def get_aware_dt_for_timezone(self, dt: DateTime, tzid: str) -> DateTime:
    """Return the timezone aware DateTime object for a given TimeZone identifier."""
    return self.get_timezone(tzid).convert_naive_datetime_to_aware(dt)

get_limited_timeline(start, end)

Return a timeline of VEvents limited by start and end

Parameters:

Name Type Description Default
start Optional[DateTime]

Only include events in the timeline with a starting date later than this value.

 required
end Optional[DateTime]

Only include events in the timeline with a starting date earlier than this value.

 required
Source code in ical_library/ical_components/v_calendar.py 
121
122
123
124
125
126
127
128
129
130
def get_limited_timeline(self, start: Optional[DateTime], end: Optional[DateTime]) -> "Timeline":
    """
    Return a timeline of VEvents limited by *start* and *end*

    :param start: Only include events in the timeline with a starting date later than this value.
    :param end: Only include events in the timeline with a starting date earlier than this value.
    """
    from ical_library.timeline import Timeline

    return Timeline(self, start, end)

get_original_ical_text(start_line, end_line)

Get the original iCAL text for your property from the RAW string list.

Parameters:

Name Type Description Default
start_line int

The starting line index for the component you wish to show.

 required
end_line int

The ending line index for the component you wish to show.

 required

Returns:

Type Description
str

The complete string, as it was in the RAW string list, for the component you wish to show.
Source code in ical_library/ical_components/v_calendar.py 
142
143
144
145
146
147
148
149
150
151
152
def get_original_ical_text(self, start_line: int, end_line: int) -> str:
    """
    Get the original iCAL text for your property from the RAW string list.
    :param start_line: The starting line index for the component you wish to show.
    :param end_line: The ending line index for the component you wish to show.
    :return: The complete string, as it was in the RAW string list, for the component you wish to show.
    """
    lines = self._lines
    if lines is None:
        raise TypeError("We should first parse the component section before calling this function.")
    return "\n".join(line for line in self.tree_root._lines[max(0, start_line) : min(len(lines), end_line)])

get_timezone(tzid)

Get the corresponding VTimeZone object based on the given timezone identifier.

Source code in ical_library/ical_components/v_calendar.py 
103
104
105
106
107
108
def get_timezone(self, tzid: str) -> VTimeZone:
    """Get the corresponding VTimeZone object based on the given timezone identifier."""
    for timezone in self.time_zones:
        if timezone.tzid.value == tzid:
            return timezone
    raise ValueError(f"Could not find Timezone with {tzid=}.")

parse_component(lines, line_number)

Parse a new component in the RAW string list.

Parameters:

Name Type Description Default
lines List[str]

A list of all the lines in the iCalendar file.

 required
line_number int

The line number at which this component starts.

 required

Returns:

Type Description
int

The line number at which this component ends.
Source code in ical_library/ical_components/v_calendar.py 
132
133
134
135
136
137
138
139
140
def parse_component(self, lines: List[str], line_number: int) -> int:
    """
    Parse a new component in the RAW string list.
    :param lines: A list of all the lines in the iCalendar file.
    :param line_number: The line number at which this component starts.
    :return: The line number at which this component ends.
    """
    self._lines = lines
    return super().parse_component(lines=lines, line_number=line_number)