Upgrade guide#

This chapter describes how to upgrade icalendar to the latest version from previous versions. Its purpose is to help developers adapt their existing code.

This guide includes only breaking changes and deprecation notices. For a comprehensive list of new features and bug fixes, see the Change log.

8.0.0#

This section describes the major changes to icalendar in version 8.0.0.

Breaking changes#

This section describes the breaking changes in icalendar 8.0.0, and how to adapt your code to these changes.

Component.from_ical no longer reads files from a str path#

Component.from_ical no longer reads a file when it is given a str that matches a path on the file system. str and bytes values are now always parsed as iCalendar data. This prevents untrusted input from causing unintended local file reads.

If your code passes a file path as a str:

from icalendar import Calendar

calendar = Calendar.from_ical("/path/to/calendar.ics")

…then pass a pathlib.Path instead.

from pathlib import Path

from icalendar import Calendar

calendar = Calendar.from_ical(Path("/path/to/calendar.ics"))

vBinary.obj removed#

vBinary.obj corrupted data. Use vBinary.bytes instead.

The example below shows how to correctly access binary data:

>>> from icalendar import Calendar
>>> cal = Calendar.example("rfc_7986_image.ics")
>>> v_binary = cal.events[1]["IMAGE"]
>>> v_binary.bytes[:4]  # correct access for PNG image data
b'\x89PNG'

For backward compatibility, if corrupt data is acceptable and you need to get the bytes as a Unicode string, use to_unicode() as shown in the following code:

>>> from icalendar.parser_tools import to_unicode
>>> string = to_unicode(v_binary.bytes)  # corrupts data

Functions removed from icalendar.parser.string#

These functions have been removed from icalendar.parser.string:

  • escape_char

  • escape_string

  • foldline,

  • unescape_char

  • unescape_string

7.0.0#

This section describes the major changes to icalendar in version 7.0.0.

Developers may be concerned about upgrading to a new major release. Upgrading from 6.x to 7.x should have no complications for most developers, because:

  • the core API stays compatible with 4.x

  • the breaking changes likely affect you only if you are an icalendar expert, not a normal user

We still recommend checking out the new features and giving feedback in the repository.

Breaking changes#

This section describes the breaking changes in icalendar 7.0.0, and how to adapt your code to these changes.

Python 3.8 and 3.9 support#

Python 3.8 and 3.9 have reached end of life.

Support for Python 3.8 and 3.9 is removed in icalendar 7.0.0.

See also

Component.decoded return type changed#

The method Component.decoded now returns a string instead of bytes for text properties.

Property creation error change#

icalendar now correctly throws a TypeError for wrong types during property creation, instead of a ValueError.

If your code expects a ValueError when creating a property, then you should change your code to use TypeError.

Moved types_factory#

types_factory was moved into Component.types_factory.

Adjust your imports from the old location of types_factory:

from icalendar import cal

…to the new location.

from icalendar.cal.component import Component

Moved components_factory#

components_factory was moved into Component.get_component_class.

Adjust your imports from the old location of components_factory:

from icalendar import cal

…to the new location.

from icalendar.cal.component import Component

Moved IncompleteComponent#

The error icalendar.cal.IncompleteComponent was moved to icalendar.error.IncompleteComponent.

Adjust your imports from the old location of IncompleteComponent:

from icalendar.cal import IncompleteComponent

…to the new location.

from icalendar.error import IncompleteComponent

Removed icalendar.UIDGenerator#

icalendar.UIDGenerator was removed. Use the Python standard library's uuid module instead.

6.0.0#

This section describes the major changes to icalendar in version 6.0.0.

Deprecations#

The following deprecation notice describes which features may be removed in a future major release of icalendar.

pytz support#

zoneinfo is the recommended replacement for pytz. zoneinfo was added in Python 3.9, and is not available in Python 3.8.

In icalendar 6.0.0a, full support for zoneinfo was added. pytz may still be used, but developers are encouraged to follow the advice of the maintainers of pytz and move to zoneinfo.