Skip to content

Commit ee113cf

Browse files
1789-follow-up-xcal-support (#2132)
* Follow up to 1789 xCal support - Rename XCalComponentParser to XCalComponentsParser * Use terminology from RFC 6321 * Add glossary terms and cross-references * Link to Python Element class * Add docstrings for xcal.adapter * Add missing docstring sections to xcal.base * Clean up docstrings in xcal.parameters * Clean up docstrings of xcal.property * Polish docstrings for xcal/string - Add a glossary term and definition for XSD and friends - Add datatypes to Vale dictionary * Update docstrings for xcal.wrapper - Convert comment to TODO for greater visibility. * Clean up docstrings in parser.parameter * Clean up docstrings in prop.dt.date * Clean up docstrings in prop.dt.datetime * Clean up docstrings in prop.dt.duration * ruff * Clean up the remaining docstrings. Most are repetitive. * Fix Sphinx warnings. * news * Standardize xCal properties * Apply most but not all batched suggestions from code review Co-authored-by: Nicco Kunzmann <niccokunzmann@rambler.ru> * Update src/icalendar/cal/journal.py * Apply batched suggestions from code review Co-authored-by: Steve Piercy <web@stevepiercy.com> * Apply suggestion from @niccokunzmann Co-authored-by: Nicco Kunzmann <niccokunzmann@rambler.ru> * Ruff * Update docs/reference/glossary.rst --------- Co-authored-by: Nicco Kunzmann <niccokunzmann@rambler.ru>
1 parent ca1f50a commit ee113cf

44 files changed

Lines changed: 330 additions & 171 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/explanation/safe-xml-parsing.rst‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,6 +46,6 @@ Therefore, icalendar is safe to use its configured built-in XML parsing.
4646
Developers can `open an issue <https://github.com/PyCalendar/icalendar/issues/new?template=empty-issue.md>`_ to use a different XML parser.
4747
The parser is configurable through the setting :func:`icalendar.config.parse_xml`.
4848

49-
.. seealso::
49+
.. seealso::
5050

51-
:mod:`icalendar.tests.rfc_6321_xcal.test_xml_parser`
51+
:file:`icalendar.tests.rfc_6321_xcal.test_xml_parser`

‎docs/reference/glossary.rst‎

Lines changed: 67 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,8 +67,74 @@ Glossary
6767
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.
6868

6969
All calendar components start with the letter "V".
70-
For example, "VEVENT" refers to the event calendar component.
70+
For example, VEVENT refers to the event calendar component.
7171

7272
.. seealso::
7373

7474
:rfc:`5545#section-3.6`
75+
76+
iCalendar object
77+
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.
78+
79+
Typically, an :term:`iCalendar stream` contains a single iCalendar object.
80+
However, multiple iCalendar objects can be sequentially grouped together in an iCalendar stream.
81+
82+
iCalendar stream
83+
At the top level of the iCalendar object model is an iCalendar stream.
84+
An iCalendar stream can contain one or more iCalendar objects.
85+
86+
.. seealso::
87+
88+
:term:`IC:icalendar`
89+
90+
IC:icalendar
91+
In xCal, an IC:icalendar XML element representation of an :term:`iCalendar stream`.
92+
93+
.. seealso::
94+
95+
:rfc:`6321#section-3.2`
96+
97+
IC:vcalendar
98+
In xCal, an IC:vcalendar XML element representation of a single :term:`iCalendar object` in an :term:`iCalendar stream`.
99+
100+
.. seealso::
101+
102+
:rfc:`6321#section-3.2`
103+
104+
IC:components
105+
In :term:`xCal`, an IC:components element is an XML element that contains zero or more :term:`component element`\ s.
106+
107+
.. seealso::
108+
109+
:rfc:`6321#section-3.2`
110+
111+
component element
112+
In :term:`xCal`, a component element represents the :term:`iCalendar` :term:`component`.
113+
Its name is the same as that in iCalendar, but lowercase.
114+
115+
.. seealso::
116+
117+
:rfc:`6321#section-3.3`
118+
119+
IC:properties
120+
In xCal, an IC:property is an XML element representation of an :term:`iCalendar` :term:`property`.
121+
Its name is the same as that in iCalendar, but lowercase.
122+
123+
.. seealso::
124+
125+
:rfc:`6321#section-3.4`
126+
127+
IC:parameters
128+
In xCal, an IC:parameter is an XML element representation of an :term:`iCalendar` :term:`parameter`.
129+
Its name is the same as that in iCalendar, but lowercase.
130+
131+
.. seealso::
132+
133+
:rfc:`6321#section-3.5`
134+
135+
XSD
136+
XML Schema Definition
137+
XML Schema Definition Language
138+
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.
139+
The names of datatypes typically begin with either ``xs:`` or ``xsd:``.
140+
The xCal specification :rfc:`6321` uses the latter, and, therefore, so does icalendar.

‎docs/styles/config/vocabularies/icalendar/accept.txt‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@ __new__
44
Args
55
backported
66
contentline
7+
datatypes?
78
(?i)datetime
89
defusedxml
910
dicts

‎news/1789.documentation‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
Follow up to :pr:`1789` to enhance docstrings. @stevepiercy

‎src/icalendar/cal/component.py‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1220,7 +1220,8 @@ def to_xcal(
12201220
- :class:`bytes` if called with no arguments.
12211221
12221222
Raises:
1223-
TypeError: If ``destination`` is neither an XML Element nor a file-like
1223+
TypeError: If ``destination`` is neither an XML
1224+
:class:`~xml.etree.ElementTree.Element` nor a file-like
12241225
object, or if ``indent`` is neither an integer nor a string.
12251226
~icalendar.error.InvalidCalendar: If an XML property cannot be written
12261227
to xCal. See :meth:`vXml.to_xcal() <icalendar.prop.xml.vXml.to_xcal>`.
@@ -1341,7 +1342,7 @@ def from_xcal(cls, xcal: Element | bytes | Path | BinaryIO) -> list[Self]:
13411342
True
13421343
13431344
"""
1344-
from icalendar.parser.xcal.component import XCalComponentParser
1345+
from icalendar.parser.xcal.component import XCalComponentsParser
13451346

13461347
if isinstance(xcal, Path):
13471348
xcal = xcal.open("rb")
@@ -1355,7 +1356,7 @@ def from_xcal(cls, xcal: Element | bytes | Path | BinaryIO) -> list[Self]:
13551356
raise TypeError(
13561357
f"Expected an XML Element, bytes, Path, or file object. Got {xcal}"
13571358
)
1358-
parser = XCalComponentParser(
1359+
parser = XCalComponentsParser(
13591360
element, cls._get_component_factory(), cls.types_factory
13601361
)
13611362
components = []

‎src/icalendar/cal/journal.py‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -152,7 +152,10 @@ def start(self, value: datetime | date) -> None:
152152

153153
@property
154154
def duration(self) -> timedelta:
155-
"""The journal has no duration: timedelta(0)."""
155+
"""The journal has no duration.
156+
Returns:
157+
``timedelta(0)``
158+
"""
156159
return timedelta(0)
157160

158161
color = color_property

‎src/icalendar/config.py‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -5,11 +5,11 @@
55
from xml.etree.ElementTree import Element, ElementTree, parse
66

77
MAX_ALARM_REPEAT: int = 10_000
8-
"""Cap on additional triggers expanded from a ``VALARM`` ``REPEAT`` property.
8+
"""Cap on additional triggers expanded from a VALARM REPEAT property.
99
10-
:rfc:`5545#section-3.8.6.2` defines ``REPEAT`` as an ``INTEGER`` data type, which is
10+
:rfc:`5545#section-3.8.6.2` defines REPEAT as an INTEGER data type, which is
1111
defined in :rfc:`5545#section-3.3.8` as an integer between -2147483648 and 2147483647.
12-
A value for ``REPEAT`` that is greater than approximately ``10_000`` can exhaust memory
12+
A value for REPEAT that is greater than approximately ``10_000`` can exhaust memory
1313
or CPU. The default value of ``10_000`` is a practical setting, but may be adjusted to
1414
specific use cases. Set to ``-1`` to disable the cap, which should be done only for
1515
fully trusted input.
@@ -32,7 +32,7 @@ def _clamp_repeat(n: int) -> int:
3232

3333

3434
def parse_xml(source) -> ElementTree[Element[str]]:
35-
"""Parse xml from source.
35+
"""Parse XML from source.
3636
3737
This wraps :func:`xml.etree.ElementTree.parse`.
3838
It makes the XML parser configurable.
@@ -45,7 +45,7 @@ def parse_xml(source) -> ElementTree[Element[str]]:
4545
:ref:`safe-xml-parsing`
4646
4747
Parameters:
48-
source: A file-like object to with a ``read`` method.
48+
source: Required. A file-like object to parse with a ``read`` method.
4949
5050
Returns:
5151
The parsed XML tree.

‎src/icalendar/parser/parameter.py‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -605,10 +605,10 @@ def from_jcal_property(cls, jcal_property: list):
605605

606606
@classmethod
607607
def from_xcal(cls, element: Element | ElementAdapter) -> Parameters:
608-
"""Parse xCal from :rfc:`6321`.
608+
"""Parse xCal according to :rfc:`6321`.
609609
610610
Parameters:
611-
element: The xCal element to parse.
611+
element: Required. The xCal element to parse.
612612
613613
Raises:
614614
~error.XCalParsingError: If the provided xCal is invalid.
@@ -649,7 +649,8 @@ def to_xcal(self, element: Element) -> None:
649649
in the element.
650650
651651
Parameters:
652-
element: The parameters are added to this element as first child.
652+
element: Required. The parameters are added to this element as the
653+
first child.
653654
"""
654655
if not self or (len(element) >= 1 and element[0].tag == "parameters"):
655656
return # exit quickly
@@ -682,7 +683,10 @@ def to_xcal(self, element: Element) -> None:
682683
element.insert(0, result)
683684

684685
def get_multiple(self, key: str) -> list:
685-
"""Get mulitple values as a list.
686+
"""Get multiple values as a list.
687+
688+
Parameters:
689+
key: Required. The key of the parameter to get.
686690
687691
.. note::
688692

‎src/icalendar/parser/property.py‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -28,7 +28,7 @@ def unescape_list_or_string(val: str | list[str]) -> str | list[str]:
2828
def unescape_backslash(val: str) -> str:
2929
r"""Unescape backslash sequences in iCalendar text.
3030
31-
Unlike :func:`~icalendar.parser.string.unescape_string`, this only handles
31+
Unlike ``_unescape_string``, this only handles
3232
actual backslash escapes per :rfc:`5545`, not URL encoding. This preserves
3333
URL-encoded values like ``%3A`` in URLs.
3434

‎src/icalendar/parser/xcal/adapter.py‎

Lines changed: 25 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -71,7 +71,14 @@ def children(self) -> list[ChildElementAdapter]:
7171
return children
7272

7373
def get_child_with_tag(self, tag: str) -> ChildElementAdapter | None:
74-
"""Get the first child element with the given tag."""
74+
"""Get the first child element with the given tag.
75+
76+
Parameters:
77+
tag: Required. The tag to search for.
78+
79+
Returns:
80+
The first child element with the given tag, or ``None`` if not found.
81+
"""
7582
tag = tag.lower()
7683
for child in self.children:
7784
if child.tag == tag:
@@ -81,6 +88,9 @@ def get_child_with_tag(self, tag: str) -> ChildElementAdapter | None:
8188
def parse_tag(self, tag: str):
8289
"""Get the first child element with the given tag.
8390
91+
Parameters:
92+
tag: Required. The tag to search for.
93+
8494
Returns:
8595
The first child element with the given tag.
8696
@@ -144,7 +154,14 @@ def __repr__(self) -> str:
144154
return f"Element@{self.get_xpath()}"
145155

146156
def make_parent(self, tag: str) -> ElementAdapter:
147-
"""Return an element adapter for a parent."""
157+
"""Return an element adapter for a parent.
158+
159+
Parameters:
160+
tag: Required. The tag for the parent element.
161+
162+
Returns:
163+
The element adapter for the parent element.
164+
"""
148165
parent = Element(tag)
149166
parent.append(self._element)
150167
return ElementAdapter(parent)
@@ -153,6 +170,9 @@ def get_inner_text(self) -> str:
153170
"""Return the inner text.
154171
155172
This is useful when there is a broken property.
173+
174+
Returns:
175+
The inner text of the element.
156176
"""
157177
return self.get_xsd_string()
158178

@@ -161,9 +181,10 @@ class ChildElementAdapter(ElementAdapter):
161181
"""An adapter class with convenience methods for child elements.
162182
163183
Parameters:
164-
child: The child element.
184+
child: Required. The child element.
185+
parent: Required. The parent element adapter.
165186
index: The index for building the XPath in the parent.
166-
parent: The parent element adapter.
187+
Default is ``1``.
167188
"""
168189

169190
def __init__(self, child: Element, parent: ElementAdapter, index: int = 1) -> None:

0 commit comments

Comments
 (0)