docs: replace RFC copy-paste docstrings with Pythonic docstrings by ykd007 · Pull Request #1385 · collective/icalendar

ykd007 · 2026-05-14T09:48:44Z

Rewrites RFC copy-paste docstrings across Alarm, Component, and Calendar into clean Pythonic format with concise summaries, examples, and see-also references.

Updated (12 properties across 3 files):

Alarm: ACKNOWLEDGED, TRIGGER
Component: DTSTAMP/stamp, LAST_MODIFIED, CREATED
Calendar: calendar_name, description, color, prodid, version, calscale, method, refresh_interval

All 3 files pass py_compile syntax check.

read-the-docs-community · 2026-05-14T09:49:37Z

Documentation build overview

📚 icalendar | 🛠️ Build #32835337 | 📁 Comparing 7c55781 against latest (66fb3e1)

🔍 Preview build

37 files changed · + 1 added · ± 36 modified

+ Added

_modules/icalendar/compatibility.html

± Modified

stevepiercy · 2026-05-20T06:55:57Z

@ykd007 would you please resolve the merge conflicts by moving your change log entry into the new format that we adopted in 7.1.2, as documented at https://icalendar.readthedocs.io/en/stable/contribute/index.html#change-log-entry-format?

stevepiercy · 2026-05-20T10:19:00Z

@ykd007 would you also edit your PR description from Closes #1244 to See #1244? We don't want to close it until all the docstrings are checked off the list.

stevepiercy

This is phenomenal work! Thank you!

There are some weird prepended and appended docstrings from a parent method that I'd like to see added to this PR, which will improve other docstrings automatically.

The change log needs to be moved, per the release of 7.1.1, and described in https://icalendar.readthedocs.io/en/stable/contribute/index.html#change-log-entry-format.

Other than that, I pretty much had only grammar and style fixes.

stevepiercy · 2026-05-20T08:46:54Z

+    Defined in :rfc:`9074`. Setting this property allows calendar clients to
+    dismiss or suppress an alarm across multiple devices. Once set to a value
+    greater than or equal to the alarm's computed trigger time, conforming clients
+    will not re-fire the alarm.


Suggested change

will not re-fire the alarm.

will not refire the alarm.

stevepiercy · 2026-05-20T08:50:08Z

+            >>> from icalendar import Alarm
+            >>> alarm = Alarm()
+            >>> alarm.ACKNOWLEDGED = datetime(2024, 1, 15, 10, 0, 0, tzinfo=timezone.utc)
+            >>> alarm.ACKNOWLEDGED  # doctest: +ELLIPSIS


Inline comments don't render. Is the comment necessary?

Suggested change

>>> alarm.ACKNOWLEDGED # doctest: +ELLIPSIS

>>> alarm.ACKNOWLEDGED

stevepiercy · 2026-05-20T08:50:10Z

+            datetime.datetime(2024, 1, 15, 10, 0, tzinfo=...)
+
+    See also:
+        :attr:`TRIGGER` — the time at which the alarm fires.


Suggested change

:attr:`TRIGGER` — the time at which the alarm fires.

:attr:`TRIGGER`, the time at which the alarm fires.

stevepiercy · 2026-05-20T10:26:39Z

+    Analogous to a file's modification timestamp. This property is optional;
+    when absent, :attr:`last_modified` falls back to :attr:`DTSTAMP`.


Suggested change

Analogous to a file's modification timestamp. This property is optional;

when absent, :attr:`last_modified` falls back to :attr:`DTSTAMP`.

It's analogous to a file's modification timestamp. This property is optional.

When it's absent, :attr:`last_modified` falls back to :attr:`DTSTAMP`.

stevepiercy · 2026-05-20T10:27:13Z

+    Analogous to a file's modification timestamp. This property is optional;
+    when absent, :attr:`last_modified` falls back to :attr:`DTSTAMP`.
+
+    Applicable to ``VEVENT``, ``VTODO``, ``VJOURNAL``, and ``VTIMEZONE``


Suggested change

Applicable to ``VEVENT``, ``VTODO``, ``VJOURNAL``, and ``VTIMEZONE``

This property is applicable to ``VEVENT``, ``VTODO``, ``VJOURNAL``, and ``VTIMEZONE``

stevepiercy · 2026-05-20T10:28:18Z

-        store.
+        """The UTC datetime when this calendar component was first created, per :rfc:`5545#section-3.8.7.1`.
+
+    Records when the calendar user agent originally stored the component.


Suggested change

Records when the calendar user agent originally stored the component.

This property records when the calendar user agent originally stored the component.

stevepiercy · 2026-05-20T10:28:36Z

+        """The UTC datetime when this calendar component was first created, per :rfc:`5545#section-3.8.7.1`.
+
+    Records when the calendar user agent originally stored the component.
+    This property is optional; when absent, :attr:`created` falls back to


Suggested change

This property is optional; when absent, :attr:`created` falls back to

This property is optional. When it's absent, :attr:`created` falls back to

stevepiercy · 2026-05-20T10:28:50Z

-            The property can be specified once in "VEVENT",
-            "VTODO", or "VJOURNAL" calendar components.  The value MUST be
-            specified as a date with UTC time.
+    Applicable to ``VEVENT``, ``VTODO``, and ``VJOURNAL`` components.


Suggested change

Applicable to ``VEVENT``, ``VTODO``, and ``VJOURNAL`` components.

This property is applicable to ``VEVENT``, ``VTODO``, and ``VJOURNAL`` components.

stevepiercy · 2026-05-25T01:01:04Z

@ykd007 in addition to addressing my comments, would you please:

Follow our new change log format, as described in https://icalendar.readthedocs.io/en/stable/contribute/index.html#change-log-entry-format?
Revert your changes to CHANGES.rst? This will also resolve the merge conflicts.

Please let us know if you need assistance with moving this forward. Thank you!

…llective#1385

ykd007 · 2026-05-25T03:04:41Z

Thank you for the detailed feedback, @stevepiercy!

I've pushed two commits addressing your requests:

Reverted CHANGES.rst to match upstream and added a towncrier news fragment at news/1385.documentation following the new format.
Updated the single_utc_property prepended docstring to The {name} property with all values converted to a ``:class:~datetime.datetime in UTC. with proper blank-line separation.
Updated the ACKNOWLEDGED docs first line to match your suggested text.
Cleaned up the p_doc boilerplate in create_single_property to use del/None literals and restructured the parameter note.

Please let me know if anything else needs attention!

stevepiercy · 2026-05-25T03:32:01Z

@ykd007 GitHub shows that there are merge conflicts that need to be resolved. Would you please take care of that? Then I can complete a review and proceed. Thank you!

…lective#1244) Rewrote RFC-verbatim docstrings for the following properties: alarm.py: - Alarm.ACKNOWLEDGED: replaced RFC 9074 Purpose/Description wall-of-text with a concise summary, Return, Example and See also sections. - Alarm.TRIGGER: replaced RFC 5545 Purpose/Value-Type verbatim with a clear summary, type info, Example and See also. component.py: - Component.DTSTAMP / stamp: replaced 'RFC 5545: Conformance/Description' block with a Pythonic summary, context note, Example and See also. - Component.LAST_MODIFIED: same pattern - Pythonic summary, Example, See also. - Component.CREATED: same pattern - Pythonic summary, Example, See also. calendar.py: - Calendar.calendar_name: removed Property Parameters/Conformance/Description RFC headings; added See also. - Calendar.description: same cleanup. - Calendar.color: removed Property Parameters/Conformance/Description RFC headings; added CSS3 link reference and See also. - Calendar.prodid: replaced Conformance/Description verbatim with Pythonic summary, Example and See also. - Calendar.version: replaced Purpose RFC text with Pythonic summary + Example. - Calendar.calscale: replaced Conformance/Description/Compatibility with Pythonic summary, RFC 7529 note, Example and See also. - Calendar.method: replaced Description RFC block with Pythonic summary, iTIP/RFC 5546 reference, Example and See also. - Calendar.refresh_interval: replaced Conformance/Description headings with Pythonic summary, updated Raises, added Example and See also.

…llective#1385

ykd007 · 2026-05-25T05:25:13Z

Hi @stevepiercy — I've rebased on current main and resolved all merge conflicts. The branch is clean now. Also tightened a few things during the rebase:

Removed the duplicate :rfc:9074`` reference in the ACKNOWLEDGED docstring
Fixed the invalid :rfc:5545#section-3.8.6.3 role (section anchors aren't supported) to just `:rfc:`5545
Cleaned up the p_doc boilerplate in create_single_property to plain prose instead of a misapplied Parameters section

Should be conflict-free now — please let me know if anything else needs attention.

coveralls · 2026-05-25T05:29:45Z

Coverage Report for CI Build 26384814733

Coverage at 97.784% (no base build to compare)

Details

Coverage remained the same as the base build.
Patch coverage: No coverable lines changed in this PR.
No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

Coverage Stats


Relevant Lines:	12717
Covered Lines:	12440
Line Coverage:	97.82%
Relevant Branches:	778
Covered Branches:	756
Branch Coverage:	97.17%
Branches in Coverage %:	Yes
Coverage Strength:	2.93 hits per line

💛 - Coveralls

…fix ACKNOWLEDGED and p_doc text

stevepiercy

I started to review your changes, but it appears you missed about two dozen of my suggestions and comments. I stopped. Would you please take care of them all? Thank you!

stevepiercy · 2026-05-25T08:07:50Z

@@ -960,10 +960,9 @@ def p_del(self: Component):
    {doc}

    Accepted values: {", ".join(t.__name__ for t in value_type)}.


Suggested change

Accepted values: {", ".join(t.__name__ for t in value_type)}.

Parameters:

{", ".join(t.__name__ for t in value_type)}.

stevepiercy · 2026-05-25T08:09:33Z

+    Raises :exc:`~icalendar.error.InvalidCalendar` if the value is invalid.
+    Returns ``None`` if absent.
+    You can also delete the value with ``del`` or by setting it to ``None``.


Please follow the docstring format.

Suggested change

Raises :exc:`~icalendar.error.InvalidCalendar` if the value is invalid.

Returns ``None`` if absent.

You can also delete the value with ``del`` or by setting it to ``None``.

Raises:

InvalidCalendar: if the attribute has invalid values.

Returns:

A :class:`~datetime.datetime` or :class:`~datetime.timedelta` if the

value is valid. ``None`` if the value is absent.

"""

stevepiercy · 2026-05-25T08:10:38Z

    {doc}



Suggested change

{doc}

{doc}

You can also delete the value with ``del`` or by setting it to ``None``.

ykd007 requested review from SashankBhamidi, angatha, niccokunzmann and stevepiercy as code owners May 14, 2026 09:48

stevepiercy requested changes May 20, 2026

View reviewed changes

ykd007 added a commit to ykd007/ikalendar that referenced this pull request May 25, 2026

fix changelog: revert CHANGES.rst, add towncrier news fragment for co…

ed3c4fb

…llective#1385

Hermes Agent and others added 3 commits May 25, 2026 10:53

fix doctests: use ELLIPSIS for tzinfo and str() for vText values

daf0edd

fix changelog: revert CHANGES.rst, add towncrier news fragment for co…

6363df5

…llective#1385

ykd007 force-pushed the fix/issue-1244-pythonic-docstrings branch from 86791a0 to ea0101f Compare May 25, 2026 05:25

address reviewer suggestions: improve single_utc_property docstring, …

7c55781

…fix ACKNOWLEDGED and p_doc text

ykd007 force-pushed the fix/issue-1244-pythonic-docstrings branch from ea0101f to 7c55781 Compare May 25, 2026 06:44

stevepiercy requested changes May 25, 2026

View reviewed changes

	>>> alarm.ACKNOWLEDGED # doctest: +ELLIPSIS
	>>> alarm.ACKNOWLEDGED

	:attr:`TRIGGER` — the time at which the alarm fires.
	:attr:`TRIGGER`, the time at which the alarm fires.

		Analogous to a file's modification timestamp. This property is optional;
		when absent, :attr:`last_modified` falls back to :attr:`DTSTAMP`.

	Applicable to ``VEVENT``, ``VTODO``, ``VJOURNAL``, and ``VTIMEZONE``
	This property is applicable to ``VEVENT``, ``VTODO``, ``VJOURNAL``, and ``VTIMEZONE``

	Records when the calendar user agent originally stored the component.
	This property records when the calendar user agent originally stored the component.

	This property is optional; when absent, :attr:`created` falls back to
	This property is optional. When it's absent, :attr:`created` falls back to

	Applicable to ``VEVENT``, ``VTODO``, and ``VJOURNAL`` components.
	This property is applicable to ``VEVENT``, ``VTODO``, and ``VJOURNAL`` components.

		@@ -960,10 +960,9 @@ def p_del(self: Component):
		{doc}

		Accepted values: {", ".join(t.__name__ for t in value_type)}.

	Accepted values: {", ".join(t.__name__ for t in value_type)}.
	Parameters:
	{", ".join(t.__name__ for t in value_type)}.

-    Raises :exc:`~icalendar.error.InvalidCalendar` if the value is invalid.
-    Returns ``None`` if absent.
-    You can also delete the value with ``del`` or by setting it to ``None``.
+    Raises:
+        InvalidCalendar: if the attribute has invalid values.
+    Returns:
+        A :class:`~datetime.datetime` or :class:`~datetime.timedelta` if the
+        value is valid. ``None`` if the value is absent.
+    """

Uh oh!

Conversation

ykd007 commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

read-the-docs-community Bot commented May 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

stevepiercy commented May 20, 2026

Uh oh!

stevepiercy commented May 20, 2026

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stevepiercy commented May 25, 2026

Uh oh!

ykd007 commented May 25, 2026

Uh oh!

stevepiercy commented May 25, 2026

Uh oh!

ykd007 commented May 25, 2026

Uh oh!

coveralls commented May 25, 2026

Coverage Report for CI Build 26384814733

Coverage at 97.784% (no base build to compare)

Details

Uncovered Changes

Coverage Regressions

Coverage Stats

💛 - Coveralls

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

ykd007 commented May 14, 2026 •

edited

Loading

read-the-docs-community Bot commented May 14, 2026 •

edited

Loading