Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
ed74548
Follow up to 1789 xCal support
stevepiercy Nov 12, 2026
65c9d19
Use terminology from RFC 6321
stevepiercy Nov 12, 2026
2d922b5
Add glossary terms and cross-references
stevepiercy Nov 13, 2026
e4f362e
Link to Python Element class
stevepiercy Nov 13, 2026
09ece69
Add docstrings for xcal.adapter
stevepiercy Nov 13, 2026
4815e83
Add missing docstring sections to xcal.base
stevepiercy Nov 13, 2026
6076a95
Clean up docstrings in xcal.parameters
stevepiercy Nov 13, 2026
c95b45a
Merge branch 'main' into 1789-follow-up-xcal-support
stevepiercy Nov 13, 2026
63a4046
Clean up docstrings of xcal.property
stevepiercy Nov 16, 2026
bccfcf2
Polish docstrings for xcal/string
stevepiercy Nov 16, 2026
fca4c75
Update docstrings for xcal.wrapper
stevepiercy Nov 16, 2026
8b17b85
Clean up docstrings in parser.parameter
stevepiercy Nov 16, 2026
6b3c7be
Clean up docstrings in prop.dt.date
stevepiercy Nov 16, 2026
20199c1
Clean up docstrings in prop.dt.datetime
stevepiercy Nov 16, 2026
8a69802
Clean up docstrings in prop.dt.duration
stevepiercy Nov 16, 2026
84e59f1
ruff
stevepiercy Nov 16, 2026
0dcc2ca
Clean up the remaining docstrings. Most are repetitive.
stevepiercy Nov 16, 2026
40e2f95
Merge branch 'main' into 1789-follow-up-xcal-support
stevepiercy Nov 16, 2026
71cdfb8
Fix Sphinx warnings.
stevepiercy Nov 16, 2026
eeafa02
news
stevepiercy Nov 16, 2026
1a7035a
Standardize xCal properties
stevepiercy Nov 18, 2026
cb0dbd5
Merge branch 'main' into 1789-follow-up-xcal-support
stevepiercy Nov 19, 2026
edf5214
Apply most but not all batched suggestions from code review
stevepiercy Nov 19, 2026
e89de5d
Update src/icalendar/cal/journal.py
stevepiercy Nov 19, 2026
29f61d9
Merge branch 'main' into 1789-follow-up-xcal-support
stevepiercy Nov 19, 2026
b02aa9b
Apply batched suggestions from code review
niccokunzmann Nov 20, 2026
9af3b5d
Apply suggestion from @niccokunzmann
stevepiercy Nov 20, 2026
c414701
Merge branch 'main' into 1789-follow-up-xcal-support
stevepiercy Nov 20, 2026
c54aca9
Ruff
stevepiercy Nov 20, 2026
246b7fe
Merge branch 'main' into 1789-follow-up-xcal-support
stevepiercy Nov 20, 2026
9169131
Merge branch 'main' into 1789-follow-up-xcal-support
stevepiercy Nov 20, 2026
55e63bb
Update docs/reference/glossary.rst
stevepiercy Nov 20, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/explanation/safe-xml-parsing.rst
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,6 @@ Therefore, icalendar is safe to use its configured built-in XML parsing.
Developers can `open an issue <https://github.com/PyCalendar/icalendar/issues/new?template=empty-issue.md>`_ 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`
68 changes: 67 additions & 1 deletion docs/reference/glossary.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Comment thread
stevepiercy marked this conversation as resolved.
Resolved
At the top level of the iCalendar object model is an iCalendar stream.
An iCalendar stream can contain one or more iCalendar objects.
Comment thread
stevepiercy marked this conversation as resolved.
Resolved

.. 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 <https://www.w3.org/TR/xmlschema11-2/>`__ (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.
1 change: 1 addition & 0 deletions docs/styles/config/vocabularies/icalendar/accept.txt
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,7 @@ __new__
Args
backported
contentline
datatypes?
(?i)datetime
defusedxml
dicts
Expand Down
1 change: 1 addition & 0 deletions news/1789.documentation
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Follow up to :pr:`1789` to enhance docstrings. @stevepiercy
7 changes: 4 additions & 3 deletions src/icalendar/cal/component.py
Original file line number Diff line number Diff line change
Expand Up @@ -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() <icalendar.prop.xml.vXml.to_xcal>`.
Expand Down Expand Up @@ -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")
Expand All @@ -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 = []
Expand Down
5 changes: 4 additions & 1 deletion src/icalendar/cal/journal.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
10 changes: 5 additions & 5 deletions src/icalendar/config.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand All @@ -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.
Expand All @@ -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.
Expand Down
12 changes: 8 additions & 4 deletions src/icalendar/parser/parameter.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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::

Expand Down
2 changes: 1 addition & 1 deletion src/icalendar/parser/property.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down
29 changes: 25 additions & 4 deletions src/icalendar/parser/xcal/adapter.py
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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.

Expand Down Expand Up @@ -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)
Expand All @@ -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()

Expand All @@ -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:
Expand Down
12 changes: 12 additions & 0 deletions src/icalendar/parser/xcal/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -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.

Expand Down Expand Up @@ -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.

Expand Down
Loading