icalendar.parser.xcal.property module#

class icalendar.parser.xcal.property.XCalPropertiesParser(element, component, types_factory)[source]#

Bases: XCalParser

A parser for <properties>.

Parameters:

element (Element | ElementAdapter) – The xCal element to parse.
component (Component) – The component to add properties to.
types_factory (TypesFactory) – The types factory to use.

Example

The parameter element can be a properties tag as shown below:

<properties>
    <prodid>
        <text>-//Example Inc.//Example Client//EN</text>
    </prodid>
    <version>
        <text>2.0</text>
    </version>
</properties>

An element in a namespace other than the iCalendar namespace becomes an XML property per RFC 6321 Section 4.1. For example, these properties contain a KML element:

<properties>
    <kml xmlns="http://www.opengis.net/kml/2.2"/>
</properties>

In iCalendar, the KML element is the value of an XML property. ElementTree chooses the namespace prefix:

XML:<ns0:kml xmlns:ns0="http://www.opengis.net/kml/2.2" />

parse_properties()[source]#

Parse properties until finished.

After this call, all properties inside the parser's element parameter have been added to the component parameter. Subsequent calls do nothing.

Raises:

XCalParsingError – If the provided xCal is invalid.
InvalidParserState – If all properties have been parsed a property value type did not parse anything.

parse_property()[source]#

Parse one property that has not been parsed, yet.

This function only parses one property inside the parser's element parameter and adds it to the component parameter. Each call parses a single property.

Raises:

XCalParsingError – If the provided xCal is invalid.
InvalidParserState – If all properties have been parsed a property value type did not parse anything.

Example

The example below shows such a property that gets parsed by one call of this method:

<prodid>
    <text>-//Example Inc.//Example Client//EN</text>
</prodid>

class icalendar.parser.xcal.property.XCalPropertyParser(element, types_factory=None)[source]#

Bases: XCalParameterParser

A parser for one property.

This parses the value type and additionally the parameters.

Parameters:

element (Element | ElementAdapter) – The xCal element to parse.
types_factory (TypesFactory | None) – The types factory to use. If None is passed, the default TypesFactory is used.

Raises:

XCalParsingError – If the provided xCal is invalid.

Examples

The parameter element can be a prodid tag with a single text value, as shown below:

<prodid>
    <text>-//Example Inc.//Example Client//EN</text>
</prodid>

Some tags, such as rdate and categories can contain multiple values. This is illustrated in the example below:

<categories>
    <text>Work</text>
    <text>Home</text>
</categories>

Additionally to the value tag, a property can contain parameters. These parameters apply to all values. The example below shows a date-time value in the timezone US/Eastern.

<dtstart>
    <parameters>
        <tzid>
            <text>US/Eastern</text>
        </tzid>
    </parameters>
    <date-time>2021-01-01T00:00:00</date-time>
</dtstart>

initialize_parameters()[source]#

Parse the parameters if present.

They only need to be parsed once. This parses the parameters tag inside of the property.

Return type:: Parameters
Returns:: If there are parameters, they are parsed returned. Otherwise, an empty Parameters object is returned.
Raises:: XCalParsingError – If the provided xCal is invalid.

parse_parameters()[source]#

Return the parsed parameters.

Return type:: Parameters
Returns:: The parsed parameters. They are identical for all property values.

parse_property_value()[source]#

Parse one property value that has not been parsed, yet.

Return type:

Returns:

The parsed property value

Raises:

XCalParsingError – If the provided xCal is invalid.
InvalidParserState – If all properties have been parsed or a property value type did not parse anything.

Example

The example below shows a text tag that this method can parse into a vText.

<text>-//Example Inc.//Example Client//EN</text>