icalendar.prop.xml module

XML values from RFC 6321.

class icalendar.prop.xml.vXml(value, encoding='utf-8', /, params=None)

Bases: vText

The value of the XML property from RFC 6321 Section 4.2.

The XML property embeds an XML element into any component. The element is in a namespace other than the iCalendar namespace. The default value type is TEXT, so the value is the XML as text. XML with the value type BINARY is a vBinary. Use element to get the XML element.

In xCal, the XML property does not exist. Instead the XML elements are directly copied into the <properties> element, see RFC 6321 Section 4.1. ElementTree chooses the namespace prefixes there.

Two values are equal if their elements have the same tags, attributes and text, whatever the namespace prefixes and the order of the attributes. Values with a document type, and other strings, are compared as text.

Parameters:

• value (str | bytes | Element | ElementAdapter) – Required. The XML as a string, bytes, an Element, or an ElementAdapter. Bytes are decoded with the encoding of their XML declaration. An element adapter keeps its path in the xCal document.

• encoding (str) – The encoding of bytes without an XML declaration.

• params (dict[str, Any] | None) – Optional parameter dictionary for the property.

Examples

Add XML to an event and get the XML element.

>>> from icalendar import Event
>>> event = Event()
>>> event.add("XML", '<a xmlns="http://example.com/ns">text</a>')
>>> print(event.to_ical().decode())
BEGIN:VEVENT
XML:<a xmlns="http://example.com/ns">text</a>
END:VEVENT
>>> event["XML"].element.tag
'{http://example.com/ns}a'

In xCal, the element is part of the properties of the event.

>>> print(event.to_xcal(indent=2).decode())
<?xml version="1.0" encoding="UTF-8"?>
<icalendar xmlns:ns0="http://example.com/ns" xmlns="urn:ietf:params:xml:ns:icalendar-2.0">
  <vevent>
    <properties>
      <ns0:a>text</ns0:a>
    </properties>
  </vevent>
</icalendar>

property element: Element

The XML element of this value.

Returns:

A new Element each time this is accessed.

Raises:

xml.etree.ElementTree.ParseError – If the value is not XML.

classmethod examples()

Examples of vXml.

Return type:

list[Self]

classmethod from_xcal(xcal)

Parse xCal from RFC 6321.

An element in a namespace other than the iCalendar namespace is the XML element of an XML property per RFC 6321 Section 4.1. An xml property element is parsed like other TEXT properties.

Parameters:

xcal (XCalParser | ElementAdapter | Element) – The XML to parse or a parser.

Return type:

Self

Returns:

The value of the XML property.

Raises:

XCalParsingError – If the provided xCal is invalid.

Example

>>> from xml.etree.ElementTree import fromstring
>>> from icalendar import vXml
>>> vXml.from_xcal(fromstring('<a xmlns="http://example.com/ns">text</a>'))
vXml(b'<ns0:a xmlns:ns0="http://example.com/ns">text</ns0:a>')

property ical_value: Element

The XML element of this value.

See also

element.

to_xcal(element)

Copy the attribute element into the parameter element.

All other property classes in icalendar.prop add children to the element parameter. vXml is special because it holds a single XML 1.0 element per RFC 6321 Section 4.1. Such an element resides directly inside the <properties> tag. Because of this, the tag, attributes, text, and children of element are replaced with the XML 1.0 element contained in this object.

Parameters:

element (Element) – The xml property element in the xCal properties.

Raises:

InvalidCalendar – If the element is not the xml property element, the XML property has parameters other than VALUE, its value is not XML, or its element either has no namespace or has the iCalendar namespace.

Return type:

None

Example

The xml property element becomes the XML element.

>>> from xml.etree.ElementTree import Element, tostring
>>> from icalendar import vXml
>>> element = Element("xml")
>>> vXml('<a xmlns="http://example.com/ns">text</a>').to_xcal(element)
>>> tostring(element)
b'<ns0:a xmlns:ns0="http://example.com/ns">text</ns0:a>'