API Reference

Create compatibility access for icalendar components.

class Description(event: Event)

Event description compatibility.

This includes HTML and text description.

Example:

>>> from icalendar import Event
>>> from icalendar_compatibility import Description
>>> event_string = '''
... BEGIN:VEVENT
... SUMMARY:Eventwith HTML
... DTSTART;TZID=Europe/London:20240414T090000
... DESCRIPTION;ALTREP="data:text/html,%3Ch1%3EKnow%20This%20Heading!%3C%2Fh1%3
...  E%3Cbr%3EPlease%20have%20a%20look%20at%20this%20website%3A%3Cbr%3E%3Ca%20hr
...  ef%3D%22https%3A%2F%2Fopen-web-calendar.quelltext.eu%2Ftemplates%2F%22%3EEx
...  amples%3C%2Fa%3E%3Cbr%3E%F0%9F%99%82%3Col%3E%3Cli%3Eone%3C%2Fli%3E%3Cli%3Et
...  wo%3C%2Fli%3E%3C%2Fol%3EAnd%20consider%20this%3A%3Cul%3E%3Cli%3Ea%20bullet%
...  20point%3C%2Fli%3E%3Cli%3Eand%20another%20bullet%20point%3C%2Fli%3E%3C%2Ful
...  %3E%3Cp%3E%3Cb%3Ebold%3C%2Fb%3E%2C%20%3Cu%3Eunderlined%3C%2Fu%3E%20and%20%3
...  Ci%3Eitalic%3C%2Fi%3E%20work!%3C%2Fp%3E%3Cpre%3Ecode%3Cbr%3Ecode%3Cbr%3Ecod
...  e%3C%2Fpre%3E":Know This Heading!\\n\\nPlease have a look at this website:\\nE
...  xamples\\n🙂\\n\\n    one\\n    two\\n\\nAnd consider this:\\n\\n    a bullet poi
...  nt\\n    and another bullet point\\n\\nbold\\, underlined and italic work!\\n\\nc
...  ode\\ncode\\ncode
... END:VEVENT
... '''
>>> event = Event.from_ical(event_string)
>>> description = Description(event)
>>> description.html[:49]
'<h1>Know This Heading!</h1><br>Please have a look'
>>> description.text[:38]
'Know This Heading!\n\nPlease have a look'

Note

Please note that sometimes there is an HTML description but not a text description.

>>> event_string = '''
... BEGIN:VEVENT
... SUMMARY:Eventwith HTML
... DTSTART;TZID=Europe/London:20240414T090000
... DESCRIPTION:<p>HTML description</p>
... END:VEVENT
... '''
>>> event = Event.from_ical(event_string)
>>> description = Description(event)
>>> description.html
'<p>HTML description</p>'
>>> description.text
''

property html: str

The event description as HTML.

The HTML description is stored in different places. This extracts the HTML description.

property raw_description: vText

The raw desctiption from the event..

property text: str

The text description of the event or an empty string.

static this_could_be_html(description: str)

Wether this is possibly HTML.

class Location(event: Event, spec: LocationSpec | None = None)

The location of an event.

Attributes:

textstr

The text of the location.

urlstr

The url of the event location. This considers geo information, text and more.

Examples:

>>> from icalendar_compatibility import Location, LocationSpec
>>> from icalendar import Event
>>> event_string = '''
... BEGIN:VEVENT
... SUMMARY:Event in Mountain View with Geo link
... DTSTART:20250115T150000Z
... LOCATION:Mountain View, Santa Clara County, Kalifornien, Vereinigte Staaten von Amerika
... GEO:37.386013;-122.082932
... END:VEVENT
... '''
>>> event = Event.from_ical(event_string)
>>> location = Location(event, LocationSpec.for_bing_com())
>>> print(location.text)
Mountain View, Santa Clara County, Kalifornien, Vereinigte Staaten von Amerika
>>> print(location.url)
https://www.bing.com/maps?brdr=1&cp=37.386013%7E-122.082932&lvl=16

property geo: vGeo | None

The geo location from latitude and longitude.

property lat: float | None

The latitude of the location.

Returns: float

The longitude or None if we have no location data.

property lon: float | None

The longitude of the location.

Returns: float

The longitude or None if we have no location data.

property raw_altrep: str

The alternative representation according to RFC5545.

RFC 5545:

LOCATION;ALTREP="http://xyzcorp.com/conf-rooms/f123.vcf":
Conference Room - F123\, Bldg. 002

property raw_geo: vGeo | None

The raw geo location.

RFC 5545:

GEO:37.386013;-122.082932

property raw_text: vText

The raw event text of the location.

RFC 5545:

LOCATION:Conference Room - F123\, Bldg. 002

property spec: LocationSpec

The location spec we use.

property text: str

The location text.

Returns: str

The text or an empty string if we have no location data.

property url: str

The location url.

Returns: str

The url or an empty string if we have no location data.

property zoom: int

The zoom level of the location.

Returns: int

The zoom level of the location.

class LocationSpec(geo_url: str, text_url: str, zoom: int = 16)

Specification for event locations.

Attributes:

zoomint

Zoom level for geo_url and search_url

geo_urlstr

A url template when the geo location is given. At least {lat} and {lon} are required.

text_urlstr

A url template when the location is given as text. At leat {location} is required.

Examples:

>>> from icalendar_compatibility import LocationSpec
>>> spec = LocationSpec.for_openstreetmap_org()

classmethod for_bing_com(**kw) → LocationSpec

Spec for https://www.bing.com/maps

classmethod for_geo_url() → LocationSpec

Spec for the geo:{lat},{lon} links.

RFC 5870:

geo:48.2010,16.3695

classmethod for_google_co_uk(**kw) → LocationSpec

Spec for https://www.google.co.uk/maps

classmethod for_google_com(**kw) → LocationSpec

Spec for https://www.google.com/maps

classmethod for_no_url() → LocationSpec

Return a spec that creates empty URLs always.

classmethod for_openstreetmap_org(**kw) → LocationSpec

Spec for https://openstreetmap.org

get_geo_url(*, lat: float, lon: float, zoom: int | None = None) → str

Get the url for a geo location.

get_text_url(location: str, zoom: int | None = None) → str

Get the url for a text location.

static quote(string: str)

Quote a string to fit into any place in a URL.

We also replace the . as .. has a special meaning.