diff --git a/docs/explanation/safe-xml-parsing.rst b/docs/explanation/safe-xml-parsing.rst index 592862cc6..6caa3ae26 100644 --- a/docs/explanation/safe-xml-parsing.rst +++ b/docs/explanation/safe-xml-parsing.rst @@ -46,6 +46,6 @@ Therefore, icalendar is safe to use its configured built-in XML parsing. Developers can `open an issue `_ to use a different XML parser. The parser is configurable through the setting :func:`icalendar.config.parse_xml`. -.. seealso:: +.. seealso:: - :mod:`icalendar.tests.rfc_6321_xcal.test_xml_parser` + :file:`icalendar.tests.rfc_6321_xcal.test_xml_parser` diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index 7a95a4bd0..4cf87c946 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -67,8 +67,74 @@ Glossary For example, the calendar component can specify an event, a to-do, a journal entry, time zone information, free/busy time information, or an alarm. All calendar components start with the letter "V". - For example, "VEVENT" refers to the event calendar component. + For example, VEVENT refers to the event calendar component. .. seealso:: :rfc:`5545#section-3.6` + + iCalendar object + As defined by :rfc:`5545#section-3.4`, an iCalendar object consists of a pair of delimiter strings—one defining its start (``BEGIN:VCALENDAR``) and the other its end (``END:VCALENDAR``), with both having trailing ``CRLF``\ s—and a body consisting of a sequence of calendar properties and one or more calendar components. + + Typically, an :term:`iCalendar stream` contains a single iCalendar object. + However, multiple iCalendar objects can be sequentially grouped together in an iCalendar stream. + + iCalendar stream + At the top level of the iCalendar object model is an iCalendar stream. + An iCalendar stream can contain one or more iCalendar objects. + + .. seealso:: + + :term:`IC:icalendar` + + IC:icalendar + In xCal, an IC:icalendar XML element representation of an :term:`iCalendar stream`. + + .. seealso:: + + :rfc:`6321#section-3.2` + + IC:vcalendar + In xCal, an IC:vcalendar XML element representation of a single :term:`iCalendar object` in an :term:`iCalendar stream`. + + .. seealso:: + + :rfc:`6321#section-3.2` + + IC:components + In :term:`xCal`, an IC:components element is an XML element that contains zero or more :term:`component element`\ s. + + .. seealso:: + + :rfc:`6321#section-3.2` + + component element + In :term:`xCal`, a component element represents the :term:`iCalendar` :term:`component`. + Its name is the same as that in iCalendar, but lowercase. + + .. seealso:: + + :rfc:`6321#section-3.3` + + IC:properties + In xCal, an IC:property is an XML element representation of an :term:`iCalendar` :term:`property`. + Its name is the same as that in iCalendar, but lowercase. + + .. seealso:: + + :rfc:`6321#section-3.4` + + IC:parameters + In xCal, an IC:parameter is an XML element representation of an :term:`iCalendar` :term:`parameter`. + Its name is the same as that in iCalendar, but lowercase. + + .. seealso:: + + :rfc:`6321#section-3.5` + + XSD + XML Schema Definition + XML Schema Definition Language + The `XML Schema Definition Language `__ (XSD) defines facilities for defining datatypes to be used in XML Schemas as well as other XML specifications. + The names of datatypes typically begin with either ``xs:`` or ``xsd:``. + The xCal specification :rfc:`6321` uses the latter, and, therefore, so does icalendar. diff --git a/docs/styles/config/vocabularies/icalendar/accept.txt b/docs/styles/config/vocabularies/icalendar/accept.txt index 6c39693e8..6f9627a30 100644 --- a/docs/styles/config/vocabularies/icalendar/accept.txt +++ b/docs/styles/config/vocabularies/icalendar/accept.txt @@ -4,6 +4,7 @@ __new__ Args backported contentline +datatypes? (?i)datetime defusedxml dicts diff --git a/news/1789.documentation b/news/1789.documentation new file mode 100644 index 000000000..48ff2ad43 --- /dev/null +++ b/news/1789.documentation @@ -0,0 +1 @@ +Follow up to :pr:`1789` to enhance docstrings. @stevepiercy diff --git a/src/icalendar/cal/component.py b/src/icalendar/cal/component.py index 953160cc6..6d2fc20f6 100644 --- a/src/icalendar/cal/component.py +++ b/src/icalendar/cal/component.py @@ -1220,7 +1220,8 @@ def to_xcal( - :class:`bytes` if called with no arguments. Raises: - TypeError: If ``destination`` is neither an XML Element nor a file-like + TypeError: If ``destination`` is neither an XML + :class:`~xml.etree.ElementTree.Element` nor a file-like object, or if ``indent`` is neither an integer nor a string. ~icalendar.error.InvalidCalendar: If an XML property cannot be written to xCal. See :meth:`vXml.to_xcal() `. @@ -1341,7 +1342,7 @@ def from_xcal(cls, xcal: Element | bytes | Path | BinaryIO) -> list[Self]: True """ - from icalendar.parser.xcal.component import XCalComponentParser + from icalendar.parser.xcal.component import XCalComponentsParser if isinstance(xcal, Path): xcal = xcal.open("rb") @@ -1355,7 +1356,7 @@ def from_xcal(cls, xcal: Element | bytes | Path | BinaryIO) -> list[Self]: raise TypeError( f"Expected an XML Element, bytes, Path, or file object. Got {xcal}" ) - parser = XCalComponentParser( + parser = XCalComponentsParser( element, cls._get_component_factory(), cls.types_factory ) components = [] diff --git a/src/icalendar/cal/journal.py b/src/icalendar/cal/journal.py index a900e9345..72ecec9d1 100644 --- a/src/icalendar/cal/journal.py +++ b/src/icalendar/cal/journal.py @@ -152,7 +152,10 @@ def start(self, value: datetime | date) -> None: @property def duration(self) -> timedelta: - """The journal has no duration: timedelta(0).""" + """The journal has no duration. + Returns: + ``timedelta(0)`` + """ return timedelta(0) color = color_property diff --git a/src/icalendar/config.py b/src/icalendar/config.py index 86ed19882..c978c3cf0 100644 --- a/src/icalendar/config.py +++ b/src/icalendar/config.py @@ -5,11 +5,11 @@ from xml.etree.ElementTree import Element, ElementTree, parse MAX_ALARM_REPEAT: int = 10_000 -"""Cap on additional triggers expanded from a ``VALARM`` ``REPEAT`` property. +"""Cap on additional triggers expanded from a VALARM REPEAT property. -:rfc:`5545#section-3.8.6.2` defines ``REPEAT`` as an ``INTEGER`` data type, which is +:rfc:`5545#section-3.8.6.2` defines REPEAT as an INTEGER data type, which is defined in :rfc:`5545#section-3.3.8` as an integer between -2147483648 and 2147483647. -A value for ``REPEAT`` that is greater than approximately ``10_000`` can exhaust memory +A value for REPEAT that is greater than approximately ``10_000`` can exhaust memory or CPU. The default value of ``10_000`` is a practical setting, but may be adjusted to specific use cases. Set to ``-1`` to disable the cap, which should be done only for fully trusted input. @@ -32,7 +32,7 @@ def _clamp_repeat(n: int) -> int: def parse_xml(source) -> ElementTree[Element[str]]: - """Parse xml from source. + """Parse XML from source. This wraps :func:`xml.etree.ElementTree.parse`. It makes the XML parser configurable. @@ -45,7 +45,7 @@ def parse_xml(source) -> ElementTree[Element[str]]: :ref:`safe-xml-parsing` Parameters: - source: A file-like object to with a ``read`` method. + source: Required. A file-like object to parse with a ``read`` method. Returns: The parsed XML tree. diff --git a/src/icalendar/parser/parameter.py b/src/icalendar/parser/parameter.py index 7168dd808..0482beab6 100644 --- a/src/icalendar/parser/parameter.py +++ b/src/icalendar/parser/parameter.py @@ -605,10 +605,10 @@ def from_jcal_property(cls, jcal_property: list): @classmethod def from_xcal(cls, element: Element | ElementAdapter) -> Parameters: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - element: The xCal element to parse. + element: Required. The xCal element to parse. Raises: ~error.XCalParsingError: If the provided xCal is invalid. @@ -649,7 +649,8 @@ def to_xcal(self, element: Element) -> None: in the element. Parameters: - element: The parameters are added to this element as first child. + element: Required. The parameters are added to this element as the + first child. """ if not self or (len(element) >= 1 and element[0].tag == "parameters"): return # exit quickly @@ -682,7 +683,10 @@ def to_xcal(self, element: Element) -> None: element.insert(0, result) def get_multiple(self, key: str) -> list: - """Get mulitple values as a list. + """Get multiple values as a list. + + Parameters: + key: Required. The key of the parameter to get. .. note:: diff --git a/src/icalendar/parser/property.py b/src/icalendar/parser/property.py index 8c0f42e54..45c7040bf 100644 --- a/src/icalendar/parser/property.py +++ b/src/icalendar/parser/property.py @@ -28,7 +28,7 @@ def unescape_list_or_string(val: str | list[str]) -> str | list[str]: def unescape_backslash(val: str) -> str: r"""Unescape backslash sequences in iCalendar text. - Unlike :func:`~icalendar.parser.string.unescape_string`, this only handles + Unlike ``_unescape_string``, this only handles actual backslash escapes per :rfc:`5545`, not URL encoding. This preserves URL-encoded values like ``%3A`` in URLs. diff --git a/src/icalendar/parser/xcal/adapter.py b/src/icalendar/parser/xcal/adapter.py index 34138c268..db73c6708 100644 --- a/src/icalendar/parser/xcal/adapter.py +++ b/src/icalendar/parser/xcal/adapter.py @@ -71,7 +71,14 @@ def children(self) -> list[ChildElementAdapter]: return children def get_child_with_tag(self, tag: str) -> ChildElementAdapter | None: - """Get the first child element with the given tag.""" + """Get the first child element with the given tag. + + Parameters: + tag: Required. The tag to search for. + + Returns: + The first child element with the given tag, or ``None`` if not found. + """ tag = tag.lower() for child in self.children: if child.tag == tag: @@ -81,6 +88,9 @@ def get_child_with_tag(self, tag: str) -> ChildElementAdapter | None: def parse_tag(self, tag: str): """Get the first child element with the given tag. + Parameters: + tag: Required. The tag to search for. + Returns: The first child element with the given tag. @@ -144,7 +154,14 @@ def __repr__(self) -> str: return f"Element@{self.get_xpath()}" def make_parent(self, tag: str) -> ElementAdapter: - """Return an element adapter for a parent.""" + """Return an element adapter for a parent. + + Parameters: + tag: Required. The tag for the parent element. + + Returns: + The element adapter for the parent element. + """ parent = Element(tag) parent.append(self._element) return ElementAdapter(parent) @@ -153,6 +170,9 @@ def get_inner_text(self) -> str: """Return the inner text. This is useful when there is a broken property. + + Returns: + The inner text of the element. """ return self.get_xsd_string() @@ -161,9 +181,10 @@ class ChildElementAdapter(ElementAdapter): """An adapter class with convenience methods for child elements. Parameters: - child: The child element. + child: Required. The child element. + parent: Required. The parent element adapter. index: The index for building the XPath in the parent. - parent: The parent element adapter. + Default is ``1``. """ def __init__(self, child: Element, parent: ElementAdapter, index: int = 1) -> None: diff --git a/src/icalendar/parser/xcal/base.py b/src/icalendar/parser/xcal/base.py index 4e2730367..26313823e 100644 --- a/src/icalendar/parser/xcal/base.py +++ b/src/icalendar/parser/xcal/base.py @@ -81,6 +81,12 @@ def parse_optional_tag(self, tag: str | Sequence[str]) -> ElementAdapter | None: """Find a child tag and return it if present, else ``None``. This child is then considered parsed. + + Parameters: + tag: Required. The tag or tags to search for. + + Returns: + The child element with the tag, or ``None`` if not found. """ tags = self._sanitize_tags(tag) return self._parse_tag(tags) @@ -90,6 +96,9 @@ def parse_tag(self, tag: str | Sequence[str] | None = None) -> ElementAdapter: This child is then considered parsed. + Parameters: + tag: The tag or tags to search for. + Returns: The child element with the tag, or if no tag is given, then the first child. @@ -145,6 +154,9 @@ def ensure_tag_is_present(self, tag: str | Sequence[str]) -> str: This serves as a check before :meth:`parse_tag`. The returned tag is not marked as parsed. + Parameters: + tag: The tag or tags to search for. + Returns: The tag that is present. diff --git a/src/icalendar/parser/xcal/component.py b/src/icalendar/parser/xcal/component.py index 7e24d542d..270960128 100644 --- a/src/icalendar/parser/xcal/component.py +++ b/src/icalendar/parser/xcal/component.py @@ -17,8 +17,10 @@ from icalendar.prop.factory import TypesFactory -class XCalComponentParser(XCalParser): - """A parser for components. +class XCalComponentsParser(XCalParser): + r"""A parser of an :term:`iCalendar stream` or :term:`IC:components` + which contain :term:`component element`\ s that yields + :class:`~icalendar.cal.component.Component`\ s. Parameters: component_factory: The component factory to use. @@ -27,8 +29,8 @@ class XCalComponentParser(XCalParser): Examples: - The ``element`` can be a an ``icalendar`` stream that contains - one or more ``vcalendar`` components. + ``element`` can be an iCalendar stream that contains + one or more :term:`IC:vcalendar` components. .. code-block:: xml @@ -38,8 +40,8 @@ class XCalComponentParser(XCalParser): - Components can contain other components inside the ``components`` tag. - The parameter ``element`` can be such a ``components`` tag. + Components can contain other components inside the :term:`IC:components` XML + element. The parameter ``element`` can be such an IC:components XML element. .. code-block:: xml @@ -48,7 +50,6 @@ class XCalComponentParser(XCalParser): ... - """ def __init__( @@ -75,16 +76,19 @@ def parse_component(self) -> Component: Raises: ~icalendar.error.XCalParsingError: If there is an error in the child. ~icalendar.parser.xcal.base.InvalidParserState: - If all components have been parsed or a property value type did not + If all components have been parsed or a property value type didn't parse anything. Example: - The XML below shows the structure of one component + The XML below shows the structure of one :term:`component element` element that gets parsed by this method. - ``vcalendar`` is the name of the component. - Each component can contain a ``properties`` and - a ``components`` element with more components. + ``vcalendar`` is the name of the component element. + The XML below shows the structure of one :term:`component element` + that gets parsed by this method. + ``vcalendar`` is the name of the component element. + Each component element can contain an :term:`IC:properties` and + an :term:`IC:components` element with more components. .. code-block:: xml @@ -112,7 +116,7 @@ def parse_component_from_child(self) -> Component: Raises: ~icalendar.error.XCalParsingError: If there is an error in the child. ~icalendar.parser.xcal.base.InvalidParserState: - If all components have been parsed or a property value type did not + If all components have been parsed or a property value type didn't parse anything. """ @@ -135,7 +139,7 @@ def parse_component_from_child(self) -> Component: properties_parser.parse_properties() components = self.child.get_child_with_tag("components") if components is not None: - components_parser = XCalComponentParser( + components_parser = XCalComponentsParser( components, self._component_factory, self._types_factory ) while not components_parser.is_finished(): @@ -143,4 +147,4 @@ def parse_component_from_child(self) -> Component: return component -__all__ = ["XCalComponentParser"] +__all__ = ["XCalComponentsParser"] diff --git a/src/icalendar/parser/xcal/parameters.py b/src/icalendar/parser/xcal/parameters.py index f702ba206..ab817d38a 100644 --- a/src/icalendar/parser/xcal/parameters.py +++ b/src/icalendar/parser/xcal/parameters.py @@ -22,7 +22,7 @@ class XCalParametersParser(XCalParser): Example: - The parameter ``element`` can be a ``parameters`` tag as shown below: + The parameter ``element`` can be an :term:`IC:parameters` tag as shown below: .. code-block:: xml @@ -52,8 +52,8 @@ def parse_parameters(self) -> Parameters: Parameters are parsed once and are the same for all property values inside a property tag. - This method parses the whole ``parameters`` tag collects them - and returns them as a :class:`~icalendar.prop.parameters.Parameters` object. + This method parses the whole :term:`IC:parameters` tag, collects them, + and returns them as a :class:`~icalendar.parser.parameter.Parameters` object. Returns: The parsed parameters. @@ -102,7 +102,13 @@ def parse_parameter(self) -> None: class XCalParameterParser(XCalParser): - """A parser for one parameter.""" + """A parser for one parameter. + + Parameters: + element: Required. The element to parse. + types_factory: The types factory to use. + + """ def __init__( self, @@ -121,15 +127,15 @@ def parse_parameter(self) -> str: """Parse one parameter value if present. Returns: - The parsed parameters. + The parsed parameter. Example: - .. code-block:: xml + .. code-block:: xml - - US/Eastern - + + US/Eastern + """ child = self.parse_tag() result = child.get_xsd_string() diff --git a/src/icalendar/parser/xcal/property.py b/src/icalendar/parser/xcal/property.py index f8dcc50b3..0fdc51623 100644 --- a/src/icalendar/parser/xcal/property.py +++ b/src/icalendar/parser/xcal/property.py @@ -20,16 +20,16 @@ class XCalPropertiesParser(XCalParser): - """A parser for . + """A parser for :term:`IC:properties`. Parameters: - element: The xCal element to parse. - component: The component to add properties to. - types_factory: The types factory to use. + component: Required. The component to add properties to. + element: Required. The xCal element to parse. + types_factory: Required. The types factory to use. Example: - The parameter ``element`` can be a ``properties`` tag as shown below: + The parameter ``element`` can be a element as shown below: .. code-block:: xml @@ -72,7 +72,7 @@ def __init__( self._component = component def parse_properties(self): - """Parse properties until finished. + """Parse multiple properties until finished. After this call, all properties inside the parser's ``element`` parameter have been added to the ``component`` parameter. @@ -81,14 +81,14 @@ def parse_properties(self): Raises: ~icalendar.error.XCalParsingError: If the provided xCal is invalid. ~icalendar.parser.xcal.base.InvalidParserState: - If all properties have been parsed a property value type - did not parse anything. + If all properties have been parsed, a property value type + parsed nothing. """ while not self.is_finished(): self.parse_property() def parse_property(self): - """Parse one property that has not been parsed, yet. + """Parse one property that hasn't been parsed yet. This function only parses one property inside the parser's ``element`` parameter and adds it to the ``component`` parameter. @@ -97,12 +97,12 @@ def parse_property(self): Raises: ~icalendar.error.XCalParsingError: If the provided xCal is invalid. ~icalendar.parser.xcal.base.InvalidParserState: - If all properties have been parsed a property value type - did not parse anything. + If all properties have been parsed, a property value type + parsed nothing. Example: - The example below shows such a property that gets parsed by one call + The example below shows a property that gets parsed by one call of this method: .. code-block:: xml @@ -156,17 +156,18 @@ class XCalPropertyParser(XCalParameterParser): This parses the value type and additionally the parameters. Parameters: - element: The xCal element to parse. + element: Required. The xCal element to parse. types_factory: The types factory to use. - If ``None`` is passed, the default TypesFactory is used. + If ``None`` is passed, the default + :class:`~icalendar.prop.factory.TypesFactory` is used. Raises: ~icalendar.error.XCalParsingError: If the provided xCal is invalid. Examples: - The parameter ``element`` can be a ``prodid`` tag with a single ``text`` - value, as shown below: + The parameter ``element`` can be a element with a single + ``text`` value, as shown below: .. code-block:: xml @@ -174,7 +175,7 @@ class XCalPropertyParser(XCalParameterParser): -//Example Inc.//Example Client//EN - Some tags, such as ``rdate`` and ``categories`` can contain + Some elements, such as and , can contain multiple values. This is illustrated in the example below: .. code-block:: xml @@ -184,9 +185,9 @@ class XCalPropertyParser(XCalParameterParser): Home - Additionally to the value tag, a property can contain parameters. + Within an element, a property can contain parameters. These parameters apply to all values. - The example below shows a ``date-time`` value in the timezone + The example below shows a value in the timezone ``US/Eastern``. .. code-block:: xml @@ -215,15 +216,14 @@ def __init__( self._parameters = self.initialize_parameters() def initialize_parameters(self) -> Parameters: - """Parse the parameters if present. + """Parse the parameters, if present. - They only need to be parsed once. - This parses the ``parameters`` tag inside - of the property. + Parameters need to be parsed only once. + This method parses the element inside the property. Returns: - If there are parameters, they are parsed returned. - Otherwise, an empty :class:`~icalendar.prop.parameters.Parameters` + If there are parameters, they are returned as parsed. + Otherwise, an empty :class:`~icalendar.parser.parameter.Parameters` object is returned. Raises: @@ -241,25 +241,25 @@ def parse_parameters(self) -> Parameters: Returns: The parsed parameters. - They are identical for all property values. + Parameters are identical for all property values. """ return self._parameters def parse_property_value(self) -> VPROPERTY: - """Parse one property value that has not been parsed, yet. + """Parse one property value that hasn't been parsed yet. Returns: - The parsed property value + The parsed property value. Raises: ~icalendar.error.XCalParsingError: If the provided xCal is invalid. ~icalendar.parser.xcal.base.InvalidParserState: If all properties have been parsed or a property value - type did not parse anything. + parsed nothing. Example: - The example below shows a ``text`` tag that this method + The example below shows a element that this method can parse into a :class:`~icalendar.prop.text.vText`. .. code-block:: xml diff --git a/src/icalendar/parser/xcal/string.py b/src/icalendar/parser/xcal/string.py index 5b1fb5067..755b47e90 100644 --- a/src/icalendar/parser/xcal/string.py +++ b/src/icalendar/parser/xcal/string.py @@ -1,4 +1,4 @@ -"""Common parsing functions based on string.""" +"""Common :term:`XSD` parsing functions based on string.""" import math import re @@ -11,8 +11,8 @@ def string_to_xsd_float(xsd_float: str) -> float: The parsed float. Raises: - ValueError: if the input is not an xsd:float - TypeError: if the input is not :class:`str` + ValueError: If the input is not an xsd:float. + TypeError: If the input is not :class:`str`. """ if not isinstance(xsd_float, str): raise TypeError("Expected xsd:float. Got None.") @@ -53,15 +53,16 @@ def xsd_float_to_string(f: float) -> str: def _to_valid_xml_string(string: str) -> str: """Remove all characters that are not valid XML characters. - Returns: + Parameters: + string: The string from which to remove invalid XML characters. + Returns: A string with all characters that are not valid XML characters removed. - .. seealso:: - - `XML Character Range `_, - `~icalendar.prop.text._strip_unsafe_text_chars`, - `Issue 1888 `_, + See also: + - `XML Character Range `_ + - ``icalendar.prop.text._strip_unsafe_text_chars`` + - `Issue 1888 `_ """ return _INVALID_XML_CHARACTERS.sub("", string) diff --git a/src/icalendar/parser/xcal/wrapper.py b/src/icalendar/parser/xcal/wrapper.py index 6a4699e8e..79db3e691 100644 --- a/src/icalendar/parser/xcal/wrapper.py +++ b/src/icalendar/parser/xcal/wrapper.py @@ -1,4 +1,4 @@ -"""Convenience methods for parsing.""" +"""Convenience methods for parsing xCal.""" from __future__ import annotations @@ -16,13 +16,13 @@ VProp = TypeVar("VProp") -# Trying to solve typing issues: https://stackoverflow.com/q/80005905/1320237 +# TODO: Trying to solve typing issues: https://stackoverflow.com/q/80005905/1320237 def from_xcal_wrapper( func: Callable[[type[VProp], XCalParser, Parameters], VProp], ) -> Callable[[type[VProp], XCalParser | ElementAdapter | Element], VProp]: - """Wrap a property's from_xcal() with convenience functions. + """Wrap a property's ``from_xcal()`` with convenience functions. Use it below ``@classmethod`` so that type checkers and linters see a class method. diff --git a/src/icalendar/parser_tools.py b/src/icalendar/parser_tools.py index a2d368789..4a200327f 100644 --- a/src/icalendar/parser_tools.py +++ b/src/icalendar/parser_tools.py @@ -2,8 +2,11 @@ from __future__ import annotations +#: The supported sequence types. SEQUENCE_TYPES = (list, tuple) +#: The default encoding to use when encoding or decoding iCalendar data. DEFAULT_ENCODING = "utf-8" +#: The type of data that can be encoded or decoded. ICAL_TYPE = str | bytes diff --git a/src/icalendar/prop/binary.py b/src/icalendar/prop/binary.py index bc8079ecc..7d2993b06 100644 --- a/src/icalendar/prop/binary.py +++ b/src/icalendar/prop/binary.py @@ -159,10 +159,11 @@ def to_xcal(self, element: Element): @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/boolean.py b/src/icalendar/prop/boolean.py index 24236e5bb..f12bc565b 100644 --- a/src/icalendar/prop/boolean.py +++ b/src/icalendar/prop/boolean.py @@ -116,10 +116,11 @@ def from_jcal(cls, jcal_property: list) -> Self: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/broken.py b/src/icalendar/prop/broken.py index 5002a54e8..3ce1774df 100644 --- a/src/icalendar/prop/broken.py +++ b/src/icalendar/prop/broken.py @@ -18,13 +18,13 @@ class vBroken(vText): Represents property values that failed to parse with their expected type. The raw iCalendar string is preserved for round-trip serialization: - ical -> xcal -> ical + ical -> xcal -> ical. """ default_value: ClassVar[str] = "X-BROKEN" - """The default value is x-broken. + """The default value is ``x-broken``. - With this, we can identify broken properties in xCal round-trip. + This identifies broken properties during an xCal round-trip. """ __slots__ = ("expected_type", "parse_error", "property_name") diff --git a/src/icalendar/prop/cal_address.py b/src/icalendar/prop/cal_address.py index 98cdab585..1a1260915 100644 --- a/src/icalendar/prop/cal_address.py +++ b/src/icalendar/prop/cal_address.py @@ -393,10 +393,11 @@ def from_jcal(cls, jcal_property: list) -> Self: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/categories.py b/src/icalendar/prop/categories.py index d02f747a7..4d025a34f 100644 --- a/src/icalendar/prop/categories.py +++ b/src/icalendar/prop/categories.py @@ -128,10 +128,11 @@ def to_xcal(self, element: Element) -> None: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/dt/date.py b/src/icalendar/prop/dt/date.py index ddcfd2b02..c834cf996 100644 --- a/src/icalendar/prop/dt/date.py +++ b/src/icalendar/prop/dt/date.py @@ -172,10 +172,10 @@ def to_xcal(self, element: Element) -> None: @classmethod def from_xcal_element(cls, element: ElementAdapter) -> date: - """Parse xCal from :rfc:`6321`. + """Parse an xCal date element according to :rfc:`6321`. Parameters: - element: The xCal element to parse. + element: Required. The xCal element to parse. Returns: The date object. @@ -194,10 +194,11 @@ def from_xcal_element(cls, element: ElementAdapter) -> date: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/dt/datetime.py b/src/icalendar/prop/dt/datetime.py index d7d2afd72..e25b14442 100644 --- a/src/icalendar/prop/dt/datetime.py +++ b/src/icalendar/prop/dt/datetime.py @@ -251,8 +251,8 @@ def to_xcal_value_only(self, element: Element, tag: str): In contrast to :meth:`to_xcal`, this method does not add the parameters. Parameters: - element: The element to add the property to. - tag: The tag to use. + element: Required. The element to add the property to. + tag: Required. The tag to use. """ element = SubElement(element, tag.lower()) text = self.dt.strftime("%Y-%m-%dT%H:%M:%S") @@ -262,10 +262,10 @@ def to_xcal_value_only(self, element: Element, tag: str): @classmethod def from_xcal_element(cls, element: ElementAdapter) -> datetime: - """Parse xCal from :rfc:`6321`. + """Parse an xCal date-time element according to :rfc:`6321`. Parameters: - element: The xCal element to parse. + element: Required. The xCal element to parse. Returns: The datetime object, possibly with a UTC timezone. @@ -326,10 +326,11 @@ def ical_value(self) -> datetime: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/dt/duration.py b/src/icalendar/prop/dt/duration.py index 35d03c533..151833560 100644 --- a/src/icalendar/prop/dt/duration.py +++ b/src/icalendar/prop/dt/duration.py @@ -237,10 +237,11 @@ def to_xcal(self, element: Element) -> None: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/dt/list.py b/src/icalendar/prop/dt/list.py index 86ecb057f..62a0353d8 100644 --- a/src/icalendar/prop/dt/list.py +++ b/src/icalendar/prop/dt/list.py @@ -132,10 +132,11 @@ def to_xcal(self, element: Element) -> None: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/dt/period.py b/src/icalendar/prop/dt/period.py index 1deb428cf..cce970b12 100644 --- a/src/icalendar/prop/dt/period.py +++ b/src/icalendar/prop/dt/period.py @@ -308,10 +308,11 @@ def to_xcal(self, element: Element) -> None: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/dt/time.py b/src/icalendar/prop/dt/time.py index bed3b10d1..bb5e932eb 100644 --- a/src/icalendar/prop/dt/time.py +++ b/src/icalendar/prop/dt/time.py @@ -282,10 +282,11 @@ def to_xcal(self, element: Element) -> None: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/dt/types.py b/src/icalendar/prop/dt/types.py index bad267e01..859bd4fd8 100644 --- a/src/icalendar/prop/dt/types.py +++ b/src/icalendar/prop/dt/types.py @@ -220,10 +220,11 @@ def to_xcal(self, element: Element) -> None: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. @@ -240,10 +241,11 @@ def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: @classmethod @from_xcal_wrapper def from_xcal_in_recur(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/dt/utc_offset.py b/src/icalendar/prop/dt/utc_offset.py index d4bb48497..479f6dcc2 100644 --- a/src/icalendar/prop/dt/utc_offset.py +++ b/src/icalendar/prop/dt/utc_offset.py @@ -198,10 +198,11 @@ def to_xcal(self, element: Element) -> None: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/empty.py b/src/icalendar/prop/empty.py index 5aa4ba025..c0595ee7e 100644 --- a/src/icalendar/prop/empty.py +++ b/src/icalendar/prop/empty.py @@ -1,4 +1,4 @@ -"""This is an value type for an empty icalendar property. +"""This is a value type for an empty iCalendar property. The calendar is invalid. This eases round trip and corrections. @@ -20,14 +20,14 @@ class vEmpty(vUnknown): - """This represents an invalid, empty property that is still there. + """This class represents an invalid, empty property to preserve parameters + during a round trip. - This is used when a property element is present but carries no typed value, + This is used when a property element is present but carries no typed value, only parameters. Storing this placeholder keeps the parameters from being - silently dropped when parsing, - while :attr:`ical_value` raises so the - broken state is visible. + silently dropped when parsing. + :attr:`ical_value` raises to make the broken state visible. Properties containing :class:`vEmpty` are invalid. However, they will be serialized correctly, repairing the calendar. @@ -78,12 +78,13 @@ def ical_value(self) -> str: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: # noqa: ARG003 - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. - This does not parse any tag but instead assumes that there is no tag. + This does not parse any element, but instead assumes that there is no element. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/float.py b/src/icalendar/prop/float.py index c0bf6ba0f..194ed2b7b 100644 --- a/src/icalendar/prop/float.py +++ b/src/icalendar/prop/float.py @@ -141,10 +141,11 @@ def from_jcal(cls, jcal_property: list) -> Self: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - element: The xCal element to parse. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/geo.py b/src/icalendar/prop/geo.py index 60b2e432e..2a3181c74 100644 --- a/src/icalendar/prop/geo.py +++ b/src/icalendar/prop/geo.py @@ -182,10 +182,11 @@ def to_xcal(self, element: Element) -> None: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - element: The xCal element to parse. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/integer.py b/src/icalendar/prop/integer.py index 634e04e17..37cb83585 100644 --- a/src/icalendar/prop/integer.py +++ b/src/icalendar/prop/integer.py @@ -172,10 +172,11 @@ def parse_jcal_value(cls, value: Any) -> int: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - element: The xCal element to parse. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. @@ -187,10 +188,11 @@ def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: @classmethod def from_xcal_element(cls, element: ElementAdapter, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - element: The xCal element to parse. + element: Required. The xCal element to parse. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. @@ -209,10 +211,11 @@ def from_xcal_element(cls, element: ElementAdapter, params: Parameters) -> Self: @classmethod @from_xcal_wrapper def from_xcal_in_recur(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - element: The xCal element to parse. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. @@ -228,7 +231,7 @@ def to_xcal(self, element: Element) -> None: class vNonNegativeInt(vInt): - """This is an integer that is supposed to be at least 0. + """This is an integer that is at least 0. See https://www.rfc-editor.org/rfc/inline-errata/rfc6321.html#btn_3050 """ diff --git a/src/icalendar/prop/recur/frequency.py b/src/icalendar/prop/recur/frequency.py index 10d611b46..0bd86ed1b 100644 --- a/src/icalendar/prop/recur/frequency.py +++ b/src/icalendar/prop/recur/frequency.py @@ -86,10 +86,11 @@ def ical_value(self) -> str: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/recur/month.py b/src/icalendar/prop/recur/month.py index fd2bda57a..13584d88f 100644 --- a/src/icalendar/prop/recur/month.py +++ b/src/icalendar/prop/recur/month.py @@ -115,10 +115,11 @@ def parse_jcal_value(cls, value: Any) -> Self: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/recur/recur.py b/src/icalendar/prop/recur/recur.py index 8e6920334..3f6b6a33d 100644 --- a/src/icalendar/prop/recur/recur.py +++ b/src/icalendar/prop/recur/recur.py @@ -500,10 +500,11 @@ def __eq__(self, other: object) -> bool: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/recur/skip.py b/src/icalendar/prop/recur/skip.py index 157cafdc9..3d51deac8 100644 --- a/src/icalendar/prop/recur/skip.py +++ b/src/icalendar/prop/recur/skip.py @@ -63,10 +63,11 @@ def parse_jcal_value(cls, value: Any) -> Self: @classmethod @from_xcal_wrapper def from_xcal_in_recur(cls, parser: XCalParser, _params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + _params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/recur/weekday.py b/src/icalendar/prop/recur/weekday.py index a8868918e..c3b3413f9 100644 --- a/src/icalendar/prop/recur/weekday.py +++ b/src/icalendar/prop/recur/weekday.py @@ -135,10 +135,11 @@ def parse_jcal_value(cls, value: Any) -> Self: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/request_status.py b/src/icalendar/prop/request_status.py index 03f1d8c8b..dfd910ee1 100644 --- a/src/icalendar/prop/request_status.py +++ b/src/icalendar/prop/request_status.py @@ -233,10 +233,11 @@ def to_xcal(self, element: Element) -> None: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/text.py b/src/icalendar/prop/text.py index 3c4e7f5c1..28fc66b87 100644 --- a/src/icalendar/prop/text.py +++ b/src/icalendar/prop/text.py @@ -43,11 +43,11 @@ def _strip_unsafe_text_chars(value: object) -> str: :class:`uuid.UUID`. Coerce those to ``str`` the same way ``str.__new__`` did before this filter ran. - .. seealso:: + .. seealso:: - :func:`~icalendar.parser.xcal.string._to_valid_xml_string` - `Issue 1712 `_, - `Issue 1888 `_, + - :func:`~icalendar.parser.xcal.string._to_valid_xml_string` + - `Issue 1712 `_ + - `Issue 1888 `_ """ if not isinstance(value, str): value = str(value) @@ -226,10 +226,11 @@ def to_xcal(self, element: Element) -> None: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. @@ -240,10 +241,11 @@ def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: @classmethod @from_xcal_wrapper def from_xcal_in_recur(cls, parser: XCalParser, _params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + _params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/unknown.py b/src/icalendar/prop/unknown.py index b4fd43b70..2466e3b17 100644 --- a/src/icalendar/prop/unknown.py +++ b/src/icalendar/prop/unknown.py @@ -50,6 +50,12 @@ class vUnknown(str): + Parameters: + value: Required. The value of the unknown property. + encoding: The encoding of the value. Default is + :data:`~icalendar.parser_tools.DEFAULT_ENCODING`. + params: The parameters of the property. + See also: :rfc:`7265#section-5.1` @@ -180,10 +186,11 @@ def to_xcal(self, element: Element) -> None: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. @@ -195,12 +202,13 @@ def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: @classmethod @from_xcal_wrapper def from_first_xcal_element(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. - This class is used as a fallback if no other type can parse this. + This class is used as a fallback if no other type can parse this xCal. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/uri.py b/src/icalendar/prop/uri.py index d8f3abccd..2f0fdd3c1 100644 --- a/src/icalendar/prop/uri.py +++ b/src/icalendar/prop/uri.py @@ -138,10 +138,11 @@ def to_xcal(self, element: Element) -> None: @classmethod @from_xcal_wrapper def from_xcal(cls, parser: XCalParser, params: Parameters) -> Self: - """Parse xCal from :rfc:`6321`. + """Parse xCal according to :rfc:`6321`. Parameters: - xml: The XML to parse or a parser. + parser: Required. The xCal to parse or a parser. + params: Required. The parameters of the xCal element. Raises: ~error.XCalParsingError: If the provided xCal is invalid. diff --git a/src/icalendar/prop/xml.py b/src/icalendar/prop/xml.py index 388747924..53383392d 100644 --- a/src/icalendar/prop/xml.py +++ b/src/icalendar/prop/xml.py @@ -66,7 +66,7 @@ class vXml(vText): Use :attr:`element` to get the XML element. In xCal, the XML property does not exist. - Instead the XML elements are directly copied into the ```` element, + Instead the XML elements are directly copied into the :term:`IC:properties` element, see :rfc:`6321#section-4.1`. :mod:`~xml.etree.ElementTree` chooses the namespace prefixes there. @@ -219,7 +219,7 @@ def to_xcal(self, element: Element) -> None: All other property classes in :mod:`icalendar.prop` add children to the ``element`` parameter. :class:`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 ```` tag. + Such an element resides directly inside the IC:properties element. Because of this, the tag, attributes, text, and children of ``element`` are replaced with the XML 1.0 element contained in this object.