icalendar.cal.lazy module#

Components for lazy parsing of components.

class icalendar.cal.lazy.InitialSubcomponentsStrategy[source]#

Bases: object

Initial strategy for the calendar.

No subcomponents.

set_components(components)[source]#

Set the subcomponents, switching to lazy parsing.

Parameters:: components (list[Component]) – The subcomponents to store. Must be empty for an uninitialised calendar.
Raises:: ValueError – If components is not empty. Parse the calendar first or use LazyCalendar.add_component() instead.
Return type:: LazySubcomponentsStrategy

class icalendar.cal.lazy.LazyCalendar(*args, **kwargs)[source]#

Bases: Calendar

A calendar that parses subcomponents lazily for memory efficiency.

Subcomponents of this calendar are parsed only when accessed, allowing the calendar to handle large files without consuming too much memory or time. All calendar-level properties are parsed immediately; subcomponents and their properties are deferred.

Examples

By accessing the events of the calendar, only Event and Timezone are immediately parsed.

>>> from icalendar import LazyCalendar
>>> calendar = LazyCalendar.example("issue_1050_all_components")
>>> len(calendar.events) == 1
True

The calendar's subcomponents were not parsed because they were not accessed. The calendar is still lazy.

>>> calendar.is_lazy()
True

When you access all subcomponents of the calendar, for example by getting their count, the entire calendar is parsed and becomes not lazy.

>>> len(calendar.subcomponents)
5
>>> calendar.is_lazy()
False

See also

ComponentIcalParser.parse

Initialize the calendar.

add_component(component)[source]#

Add a component to this calendar.

This adds a subcomponent without parsing the entire calendar. Use this, instead of appending to subcomponents which forces all subcomponents to be parsed first.

Parameters:: component (Component) – The component to add as a subcomponent.

See also

Component.add_component

Return type:: None

is_lazy()[source]#

Whether the subcomponents are still deferred and not yet parsed.

Returns True if subcomponents have not been accessed yet. Returns False once all subcomponents have been parsed, for example, by accessing subcomponents.

Note

If you believe the calendar parses more subcomponents than it should, please open an issue.

Return type:: bool
Returns:: True if subcomponent parsing is deferred. False if all subcomponents have been parsed.

property subcomponents: list[Component]#

Parse and return all subcomponents of this calendar.

Accessing this property triggers the parsing of all deferred subcomponents. Once accessed, the calendar is no longer lazy.

You can manipulate the returned list or set it to replace all subcomponents. Setting the list does not re-enable lazy parsing.

Returns:: A list of parsed subcomponents.

See also

with_uid(uid)[source]#

Return subcomponents matching the given UID without parsing all subcomponents.

This searches lazily, parsing only the minimal subcomponents needed to find matches. If this calendar's own UID matches, it is included as the first element.

Parameters:: uid (str) – The UID to search for.
Return type:: list[Component]
Returns:: A list of components whose UID matches, with the calendar itself first if it matches.

See also

Component.with_uid

class icalendar.cal.lazy.LazySubcomponentsStrategy[source]#

Bases: object

Parse subcomponents only when accessed.

add_component(component)[source]#

Add a component to the calendar without parsing it.

Parameters:: component (Component | LazySubcomponent) – The component to add.
Return type:: LazySubcomponentsStrategy
Returns:: This strategy with the component added.

property as_parsed: ParsedSubcomponentsStrategy#

Return a parsed strategy with all subcomponents parsed.

Returns:: A ParsedSubcomponentsStrategy with all subcomponents.

get_all_components()[source]#

Get the subcomponents of the calendar, parsing all of them.

Return type:: tuple[ParsedSubcomponentsStrategy, list[Component]]
Returns:: A tuple of a parsed strategy and the list of subcomponents.

initial_components_to_parse: tuple[str, ...] = ('VTIMEZONE',)#: Parse these subcomponents before any others.

is_lazy()[source]#

Return whether the subcomponents may be lazily parsed.

Return type:: bool

parse_initial_components()[source]#

Parse the components that are required by other components.

This mainly concerns the timezone components. They are required by other components that have a TZID parameter.

Return type:: None

set_components(components)[source]#

Set the subcomponents of the calendar.

Parameters:: components (list[Component]) – The subcomponents to store.
Return type:: ParsedSubcomponentsStrategy
Returns:: A ParsedSubcomponentsStrategy holding the components.

walk(name)[source]#

Get the subcomponents of the calendar with the given name.

Parse only the minimal number of subcomponents.

Parameters:: name (str | None) – The component name to filter by, or None for all.
Return type:: tuple[LazySubcomponentsStrategy, list[Component]]
Returns:: A tuple of this strategy and the matching subcomponents.

with_uid(uid)[source]#

Get the subcomponents of the calendar with the given uid.

Parse only the minimal number of subcomponents.

Parameters:: uid (str) – The UID to search for.
Return type:: tuple[LazySubcomponentsStrategy, list[Component]]
Returns:: A tuple of this strategy and the matching subcomponents.

class icalendar.cal.lazy.ParsedSubcomponentsStrategy[source]#

Bases: object

All the subcomponents are parsed and available as a list.

add_component(component)[source]#

Add a component to the calendar, parsing it immediately.

Parameters:: component (Component) – The component to add.
Return type:: ParsedSubcomponentsStrategy
Returns:: This strategy with the component added.

get_all_components()[source]#

Get the parsed subcomponents of the calendar.

Return type:: tuple[ParsedSubcomponentsStrategy, list[Component]]
Returns:: A tuple of this strategy and the list of parsed subcomponents.

is_lazy()[source]#

Return False because subcomponents are not lazily parsed.

Return type:: Literal[False]

set_components(components)[source]#

Set the subcomponents of the calendar.

Parameters:: components (list[Component]) – The parsed subcomponents to store.
Return type:: ParsedSubcomponentsStrategy
Returns:: This strategy with the subcomponents stored.

walk(name)[source]#

Get the subcomponents of the calendar with the given name.

Parameters:: name (str) – The component name to filter by, for example, "VEVENT".
Return type:: tuple[ParsedSubcomponentsStrategy, list[Component]]
Returns:: A tuple of this strategy and the matching subcomponents.

with_uid(name)[source]#

Get the subcomponents of the calendar with the given UID.

Parameters:: name (str) – The UID to search for.
Return type:: tuple[ParsedSubcomponentsStrategy, list[Component]]
Returns:: A tuple of this strategy and the matching subcomponents.