From ed74548bd42ddfc28a18c6e8532944d1f5545f1e Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 12 Nov 2026 03:06:13 -0800 Subject: [PATCH 01/25] Follow up to 1789 xCal support - Rename XCalComponentParser to XCalComponentsParser --- src/icalendar/cal/component.py | 4 ++-- src/icalendar/parser/xcal/component.py | 6 +++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/src/icalendar/cal/component.py b/src/icalendar/cal/component.py index 038158ab2..de004676a 100644 --- a/src/icalendar/cal/component.py +++ b/src/icalendar/cal/component.py @@ -1341,7 +1341,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 +1355,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/parser/xcal/component.py b/src/icalendar/parser/xcal/component.py index 7e24d542d..29b4613c4 100644 --- a/src/icalendar/parser/xcal/component.py +++ b/src/icalendar/parser/xcal/component.py @@ -17,8 +17,8 @@ from icalendar.prop.factory import TypesFactory -class XCalComponentParser(XCalParser): """A parser for components. +class XCalComponentsParser(XCalParser): Parameters: component_factory: The component factory to use. @@ -135,7 +135,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 +143,4 @@ def parse_component_from_child(self) -> Component: return component -__all__ = ["XCalComponentParser"] +__all__ = ["XCalComponentsParser"] From 65c9d1976c92cf88bcde603072ba0802298229b4 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 12 Nov 2026 03:06:57 -0800 Subject: [PATCH 02/25] Use terminology from RFC 6321 --- src/icalendar/parser/xcal/component.py | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/src/icalendar/parser/xcal/component.py b/src/icalendar/parser/xcal/component.py index 29b4613c4..d1255380b 100644 --- a/src/icalendar/parser/xcal/component.py +++ b/src/icalendar/parser/xcal/component.py @@ -17,8 +17,8 @@ from icalendar.prop.factory import TypesFactory - """A parser for components. class XCalComponentsParser(XCalParser): + """A parser of an iCalendar stream which contains xCal components that yields :class:`~icalendar.cal.component.Component`\ s. Parameters: component_factory: The component factory to use. @@ -27,8 +27,8 @@ class XCalComponentsParser(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 IC:vcalendar components. .. code-block:: xml @@ -38,8 +38,8 @@ class XCalComponentsParser(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 IC:components XML element. + The parameter ``element`` can be such an IC:components XML element. .. code-block:: xml @@ -48,7 +48,6 @@ class XCalComponentsParser(XCalParser): ... - """ def __init__( From 2d922b5543c71bc61fb06502977c9c1ff90e80c1 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 13 Nov 2026 01:57:33 -0800 Subject: [PATCH 03/25] Add glossary terms and cross-references --- docs/reference/glossary.rst | 47 +++++++++++++++++++++++++- src/icalendar/parser/xcal/component.py | 18 +++++----- 2 files changed, 55 insertions(+), 10 deletions(-) diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index 7a95a4bd0..ff2305d89 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -67,8 +67,53 @@ 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 stream + At the top level of the iCalendar object model is an iCalendar stream. + An iCalendar stream can contain one or more iCalendar objects. + + 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:component + IC:components + In xCal, an IC:component is an XML element representation of an :term:`iCalendar` :term:`component`. + Its name is the same as that in iCalendar, but lowercase. + + .. seealso:: + + :rfc:`6321#section-3.3` + + IC:property + 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:parameter + 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` diff --git a/src/icalendar/parser/xcal/component.py b/src/icalendar/parser/xcal/component.py index d1255380b..e14138588 100644 --- a/src/icalendar/parser/xcal/component.py +++ b/src/icalendar/parser/xcal/component.py @@ -18,7 +18,7 @@ class XCalComponentsParser(XCalParser): - """A parser of an iCalendar stream which contains xCal components that yields :class:`~icalendar.cal.component.Component`\ s. + """A parser of an :term:`iCalendar stream` which contains xCal components that yields :class:`~icalendar.cal.component.Component`\ s. Parameters: component_factory: The component factory to use. @@ -28,7 +28,7 @@ class XCalComponentsParser(XCalParser): Examples: ``element`` can be an iCalendar stream that contains - one or more IC:vcalendar components. + one or more :term:`IC:vcalendar` components. .. code-block:: xml @@ -38,7 +38,7 @@ class XCalComponentsParser(XCalParser): - Components can contain other components inside the IC:components XML element. + 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 @@ -74,16 +74,16 @@ 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:`IC:component` 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 IC:component. + Each IC:component can contain an :term:`IC:properties` and + an IC:components element with more components. .. code-block:: xml @@ -111,7 +111,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. """ From e4f362e4da78af584a2f3b20ea15e836e17c5230 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 13 Nov 2026 02:11:39 -0800 Subject: [PATCH 04/25] Link to Python Element class --- src/icalendar/cal/component.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/icalendar/cal/component.py b/src/icalendar/cal/component.py index de004676a..b49c6adc8 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() `. From 09ece69d9cfb3032b88f740dfb93d40b15e3f96f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 13 Nov 2026 02:21:05 -0800 Subject: [PATCH 05/25] Add docstrings for xcal.adapter --- src/icalendar/parser/xcal/adapter.py | 29 ++++++++++++++++++++++++---- 1 file changed, 25 insertions(+), 4 deletions(-) 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: From 4815e83c02d0a5a1dd81170cf4d55dd613d9779b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 13 Nov 2026 02:27:44 -0800 Subject: [PATCH 06/25] Add missing docstring sections to xcal.base --- src/icalendar/parser/xcal/base.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) 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. From 6076a9574e9376040ce6a78a371c92c9c6b8fe98 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 13 Nov 2026 02:42:03 -0800 Subject: [PATCH 07/25] Clean up docstrings in xcal.parameters --- src/icalendar/parser/xcal/parameters.py | 24 +++++++++++++++--------- 1 file changed, 15 insertions(+), 9 deletions(-) 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() From 63a4046d3a45a6a27e55b7c9beccfbeeea5c71ee Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 15 Nov 2026 17:17:41 -0800 Subject: [PATCH 08/25] Clean up docstrings of xcal.property --- src/icalendar/parser/xcal/property.py | 60 +++++++++++++-------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/src/icalendar/parser/xcal/property.py b/src/icalendar/parser/xcal/property.py index f8dcc50b3..e6821e14e 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 From bccfcf27291a77e2adcbec176d67190f293fc420 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 15 Nov 2026 22:04:58 -0800 Subject: [PATCH 09/25] Polish docstrings for xcal/string - Add a glossary term and definition for XSD and friends - Add datatypes to Vale dictionary --- docs/reference/glossary.rst | 7 +++++++ .../config/vocabularies/icalendar/accept.txt | 1 + src/icalendar/parser/xcal/string.py | 19 ++++++++++--------- 3 files changed, 18 insertions(+), 9 deletions(-) diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index ff2305d89..08e6552d4 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -117,3 +117,10 @@ Glossary .. 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 8b06f6ad5..29c244cd8 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/src/icalendar/parser/xcal/string.py b/src/icalendar/parser/xcal/string.py index dfe0f9b15..298de0e77 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.") @@ -39,15 +39,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 _VALID_XML_CHARACTERS.sub("", string) From fca4c75700af4804c3510a3f9dd6bfb51a9aa7bc Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 15 Nov 2026 22:10:12 -0800 Subject: [PATCH 10/25] Update docstrings for xcal.wrapper - Convert comment to TODO for greater visibility. --- src/icalendar/parser/xcal/wrapper.py | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) 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. From 8b17b8571b9276a8d10c92f7713a2467540bd43b Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 15 Nov 2026 22:16:04 -0800 Subject: [PATCH 11/25] Clean up docstrings in parser.parameter --- src/icalendar/parser/parameter.py | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/src/icalendar/parser/parameter.py b/src/icalendar/parser/parameter.py index 7168dd808..19022d342 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,7 @@ 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 +682,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:: From 6b3c7be9d5c93ac55063395699060ee66490f0fd Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 15 Nov 2026 22:31:56 -0800 Subject: [PATCH 12/25] Clean up docstrings in prop.dt.date --- src/icalendar/prop/dt/date.py | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) 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. From 20199c14ae9571b2e72fd0e0fef27dcd3151d2ea Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 15 Nov 2026 22:37:06 -0800 Subject: [PATCH 13/25] Clean up docstrings in prop.dt.datetime --- src/icalendar/prop/dt/datetime.py | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/src/icalendar/prop/dt/datetime.py b/src/icalendar/prop/dt/datetime.py index fec1c6795..668c1941e 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. @@ -294,10 +294,11 @@ def from_xcal_element(cls, element: ElementAdapter) -> 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. From 8a6980250dd9dca3c18ff92ca2cb93541ed56a70 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 15 Nov 2026 22:38:31 -0800 Subject: [PATCH 14/25] Clean up docstrings in prop.dt.duration --- src/icalendar/prop/dt/duration.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/icalendar/prop/dt/duration.py b/src/icalendar/prop/dt/duration.py index b4f212e87..e5b7fa7f1 100644 --- a/src/icalendar/prop/dt/duration.py +++ b/src/icalendar/prop/dt/duration.py @@ -232,10 +232,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. From 84e59f1a061291d13fa3277d435e9e24d28ce820 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 15 Nov 2026 22:56:29 -0800 Subject: [PATCH 15/25] ruff --- src/icalendar/parser/parameter.py | 3 ++- src/icalendar/parser/xcal/component.py | 7 ++++--- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/src/icalendar/parser/parameter.py b/src/icalendar/parser/parameter.py index 19022d342..0482beab6 100644 --- a/src/icalendar/parser/parameter.py +++ b/src/icalendar/parser/parameter.py @@ -649,7 +649,8 @@ def to_xcal(self, element: Element) -> None: in the element. Parameters: - element: Required. The parameters are added to this element as the 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 diff --git a/src/icalendar/parser/xcal/component.py b/src/icalendar/parser/xcal/component.py index e14138588..bb41e04f8 100644 --- a/src/icalendar/parser/xcal/component.py +++ b/src/icalendar/parser/xcal/component.py @@ -18,7 +18,8 @@ class XCalComponentsParser(XCalParser): - """A parser of an :term:`iCalendar stream` which contains xCal components that yields :class:`~icalendar.cal.component.Component`\ s. + r"""A parser of an :term:`iCalendar stream` which contains xCal components that + yields :class:`~icalendar.cal.component.Component`\ s. Parameters: component_factory: The component factory to use. @@ -38,8 +39,8 @@ class XCalComponentsParser(XCalParser): - Components can contain other components inside the :term:`IC:components` XML element. - The parameter ``element`` can be such an IC:components XML element. + 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 From 0dcc2ca218a66fbafcbb8c07f59b3ed69ec357be Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 15 Nov 2026 23:36:36 -0800 Subject: [PATCH 16/25] Clean up the remaining docstrings. Most are repetitive. --- src/icalendar/config.py | 10 +++++----- src/icalendar/parser_tools.py | 3 +++ src/icalendar/prop/binary.py | 5 +++-- src/icalendar/prop/boolean.py | 5 +++-- src/icalendar/prop/broken.py | 6 +++--- src/icalendar/prop/cal_address.py | 5 +++-- src/icalendar/prop/categories.py | 5 +++-- src/icalendar/prop/dt/list.py | 5 +++-- src/icalendar/prop/dt/period.py | 5 +++-- src/icalendar/prop/dt/time.py | 5 +++-- src/icalendar/prop/dt/types.py | 10 ++++++---- src/icalendar/prop/dt/utc_offset.py | 5 +++-- src/icalendar/prop/empty.py | 19 ++++++++++--------- src/icalendar/prop/float.py | 5 +++-- src/icalendar/prop/geo.py | 5 +++-- src/icalendar/prop/integer.py | 17 ++++++++++------- src/icalendar/prop/recur/frequency.py | 5 +++-- src/icalendar/prop/recur/month.py | 5 +++-- src/icalendar/prop/recur/recur.py | 5 +++-- src/icalendar/prop/recur/skip.py | 5 +++-- src/icalendar/prop/recur/weekday.py | 5 +++-- src/icalendar/prop/request_status.py | 5 +++-- src/icalendar/prop/text.py | 18 ++++++++++-------- src/icalendar/prop/unknown.py | 18 +++++++++++++----- src/icalendar/prop/uri.py | 5 +++-- 25 files changed, 111 insertions(+), 75 deletions(-) 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_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 7a2917232..cc3975fd1 100644 --- a/src/icalendar/prop/cal_address.py +++ b/src/icalendar/prop/cal_address.py @@ -392,10 +392,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/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 18c2f9d8c..80e660393 100644 --- a/src/icalendar/prop/float.py +++ b/src/icalendar/prop/float.py @@ -121,10 +121,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 e2383417c..964d33cd3 100644 --- a/src/icalendar/prop/geo.py +++ b/src/icalendar/prop/geo.py @@ -181,10 +181,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 09c5fca59..ff7a7f92f 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. From 71cdfb819e98c6aac58d9f7a72e2bba6b445239a Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 15 Nov 2026 23:52:22 -0800 Subject: [PATCH 17/25] Fix Sphinx warnings. --- docs/explanation/safe-xml-parsing.rst | 4 ++-- src/icalendar/cal/journal.py | 2 +- src/icalendar/parser/property.py | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) 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/src/icalendar/cal/journal.py b/src/icalendar/cal/journal.py index a900e9345..918bdb569 100644 --- a/src/icalendar/cal/journal.py +++ b/src/icalendar/cal/journal.py @@ -152,7 +152,7 @@ def start(self, value: datetime | date) -> None: @property def duration(self) -> timedelta: - """The journal has no duration: timedelta(0).""" + """The journal has no duration, or ``timedelta(0)``.""" return timedelta(0) color = color_property 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. From eeafa02e2bae2205f5c22d087423a4c2d41a4fc4 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Sun, 15 Nov 2026 23:52:27 -0800 Subject: [PATCH 18/25] news --- news/1789.documentation | 1 + 1 file changed, 1 insertion(+) create mode 100644 news/1789.documentation 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 From 1a7035ad0f2f499ad1392ea30b15f5d36d056d00 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Wed, 18 Nov 2026 01:04:38 -0800 Subject: [PATCH 19/25] Standardize xCal properties --- src/icalendar/parser/xcal/property.py | 12 ++++++------ src/icalendar/prop/xml.py | 4 ++-- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/src/icalendar/parser/xcal/property.py b/src/icalendar/parser/xcal/property.py index e6821e14e..0fdc51623 100644 --- a/src/icalendar/parser/xcal/property.py +++ b/src/icalendar/parser/xcal/property.py @@ -29,7 +29,7 @@ class XCalPropertiesParser(XCalParser): Example: - The parameter ``element`` can be a ```` element as shown below: + The parameter ``element`` can be a element as shown below: .. code-block:: xml @@ -166,7 +166,7 @@ class XCalPropertyParser(XCalParameterParser): Examples: - The parameter ``element`` can be a ```` element with a single + The parameter ``element`` can be a element with a single ``text`` value, as shown below: .. code-block:: xml @@ -175,7 +175,7 @@ class XCalPropertyParser(XCalParameterParser): -//Example Inc.//Example Client//EN - Some elements, such as ```` and ````, can contain + Some elements, such as and , can contain multiple values. This is illustrated in the example below: .. code-block:: xml @@ -187,7 +187,7 @@ class XCalPropertyParser(XCalParameterParser): Within an element, a property can contain parameters. These parameters apply to all values. - The example below shows a ```` value in the timezone + The example below shows a value in the timezone ``US/Eastern``. .. code-block:: xml @@ -219,7 +219,7 @@ def initialize_parameters(self) -> Parameters: """Parse the parameters, if present. Parameters need to be parsed only once. - This method parses the ```` element inside the property. + This method parses the element inside the property. Returns: If there are parameters, they are returned as parsed. @@ -259,7 +259,7 @@ def parse_property_value(self) -> VPROPERTY: Example: - The example below shows a ```` element 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/prop/xml.py b/src/icalendar/prop/xml.py index 388747924..a8c6dbf4f 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 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 tag. Because of this, the tag, attributes, text, and children of ``element`` are replaced with the XML 1.0 element contained in this object. From edf5214656ba4251da6aab4b89a2aa65e380b27c Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 19 Nov 2026 02:35:38 -0800 Subject: [PATCH 20/25] Apply most but not all batched suggestions from code review Co-authored-by: Nicco Kunzmann --- docs/reference/glossary.rst | 16 ++++++++++++---- src/icalendar/cal/journal.py | 6 +++++- src/icalendar/parser/xcal/component.py | 11 +++++++---- src/icalendar/prop/xml.py | 4 ++-- 4 files changed, 26 insertions(+), 11 deletions(-) diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index 08e6552d4..d9cad25e4 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -76,6 +76,10 @@ Glossary 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`. @@ -91,16 +95,21 @@ Glossary :rfc:`6321#section-3.2` - IC:component IC:components - In xCal, an IC:component is an XML element representation of an :term:`iCalendar` :term:`component`. + 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:property 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. @@ -109,7 +118,6 @@ Glossary :rfc:`6321#section-3.4` - IC:parameter 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. diff --git a/src/icalendar/cal/journal.py b/src/icalendar/cal/journal.py index 918bdb569..48f92dc29 100644 --- a/src/icalendar/cal/journal.py +++ b/src/icalendar/cal/journal.py @@ -152,7 +152,11 @@ def start(self, value: datetime | date) -> None: @property def duration(self) -> timedelta: - """The journal has no duration, or ``timedelta(0)``.""" + """The journal has no duration. + + Returns: + ``timedelta(0)`` + """ return timedelta(0) color = color_property diff --git a/src/icalendar/parser/xcal/component.py b/src/icalendar/parser/xcal/component.py index bb41e04f8..2ae4be1f3 100644 --- a/src/icalendar/parser/xcal/component.py +++ b/src/icalendar/parser/xcal/component.py @@ -80,11 +80,14 @@ def parse_component(self) -> Component: Example: - The XML below shows the structure of one :term:`IC: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 IC:component. - Each IC:component can contain an :term:`IC:properties` and - an IC: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 diff --git a/src/icalendar/prop/xml.py b/src/icalendar/prop/xml.py index a8c6dbf4f..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. From e89de5ddace20b4d1e8bcb60ffcc01ab30ae832d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 19 Nov 2026 04:04:43 -0800 Subject: [PATCH 21/25] Update src/icalendar/cal/journal.py --- src/icalendar/cal/journal.py | 1 - 1 file changed, 1 deletion(-) diff --git a/src/icalendar/cal/journal.py b/src/icalendar/cal/journal.py index 48f92dc29..72ecec9d1 100644 --- a/src/icalendar/cal/journal.py +++ b/src/icalendar/cal/journal.py @@ -153,7 +153,6 @@ def start(self, value: datetime | date) -> None: @property def duration(self) -> timedelta: """The journal has no duration. - Returns: ``timedelta(0)`` """ From b02aa9b9b759e184368a6447eba4121ff62198b8 Mon Sep 17 00:00:00 2001 From: Nicco Kunzmann Date: Fri, 20 Nov 2026 02:15:30 +0000 Subject: [PATCH 22/25] Apply batched suggestions from code review Co-authored-by: Steve Piercy --- docs/reference/glossary.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index d9cad25e4..039ac01a4 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -89,7 +89,7 @@ Glossary :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`. + In xCal, an IC:vcalendar XML element representation of a single :term:`iCalendar object` in an :term:`iCalendar stream`. .. seealso:: From 9af3b5d21e5a8bfb3f9d45173af39400f3c09e3f Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 19 Nov 2026 21:43:34 -0800 Subject: [PATCH 23/25] Apply suggestion from @niccokunzmann Co-authored-by: Nicco Kunzmann --- src/icalendar/parser/xcal/component.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/icalendar/parser/xcal/component.py b/src/icalendar/parser/xcal/component.py index 2ae4be1f3..d87ca777f 100644 --- a/src/icalendar/parser/xcal/component.py +++ b/src/icalendar/parser/xcal/component.py @@ -18,7 +18,7 @@ class XCalComponentsParser(XCalParser): - r"""A parser of an :term:`iCalendar stream` which contains xCal components that + 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: From c54aca915982f4f5b33c9080e8402ea891fdbb8d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Thu, 19 Nov 2026 21:48:11 -0800 Subject: [PATCH 24/25] Ruff --- src/icalendar/parser/xcal/component.py | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/src/icalendar/parser/xcal/component.py b/src/icalendar/parser/xcal/component.py index d87ca777f..270960128 100644 --- a/src/icalendar/parser/xcal/component.py +++ b/src/icalendar/parser/xcal/component.py @@ -18,8 +18,9 @@ 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. + 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. From 55e63bb89b595d113da49811ab5e6f6310ddbf2d Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Fri, 20 Nov 2026 02:07:14 -0800 Subject: [PATCH 25/25] Update docs/reference/glossary.rst --- docs/reference/glossary.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/reference/glossary.rst b/docs/reference/glossary.rst index 039ac01a4..4cf87c946 100644 --- a/docs/reference/glossary.rst +++ b/docs/reference/glossary.rst @@ -73,6 +73,12 @@ Glossary :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.