docs: clarify Event.new() optional and auto-generated properties by checkzhao8888 · Pull Request #1504 · collective/icalendar

checkzhao8888 · 2026-06-25T06:19:36Z

Linked issue

See Clarify auto-generated properties for new class methods #1473

Description

Clarifies the Event.new() docstring to align with RFC terminology used elsewhere in the project (for example, #1459 for Calendar.new()).

Changes:

Replace the misleading summary "with all required properties" with "Create a new event."
Mark optional parameters explicitly.
Document auto-generated UID and DTSTAMP values when arguments are None.

AI disclosure: Grok assisted with reviewing RFC terminology, comparing existing new() docstring patterns, and drafting the update.

Checklist

I've added a change log entry to /news, following the instructions in Change log entry format.
I've added or updated tests if applicable.
I've run and ensured all tests pass locally by following Run tests.
I've added or edited documentation, both as docstrings to be rendered in the API documentation and narrative documentation, as necessary.

Align Event.new() parameter documentation with RFC terminology by marking optional arguments explicitly and documenting auto-generated UID and DTSTAMP values. See collective#1473 AI: Grok — reviewed Event.required, Calendar.new (collective#1459), and Alarm.new PR patterns; drafted the docstring wording.

github-actions · 2026-06-25T06:19:47Z

Profile summary:

GitHub user: checkzhao8888
🟢 No concerns found with user's profile.
🟢 No concerns found with recent PR activity.
🟢 No concerns found with recent issue activity.

For a more detailed report, run `gh-profiler checkzhao8888`.

Full profile

GitHub user: checkzhao8888
🟢 No concerns found with user's profile.
   🟢 Account age: 5 months
   🟢 Profile information:
        name: Checkzhao
        blog: aws.checkzhao.com
        location: Singapore
        email: 475152974zhao@gmail.com
        bio:
          Former ops → AI automation solo builder.
          Building http://aws.checkzhao.com in public.
          Codex · Antigravity · GPT · agents · workflows
        twitter: https://x.com/wkngsn72674
      Empty fields: company

🟢 No concerns found with recent PR activity.
   1 PR opened in the last 21 days.
      0 opened against repos the user owns.
      0 opened against repos in publicly associated orgs.
      1 opened against external repos.

   🟢 0 of 1 external PRs merged in the last 21 days.
   🟢 0 of 1 external PRs closed without merging in the last 21 days.

🟢 No concerns found with recent issue activity.
   🟢 No new issues opened in the last 21 days.

read-the-docs-community · 2026-06-25T06:20:48Z

Documentation build overview

📚 icalendar | 🛠️ Build #33302006 | 📁 Comparing e750894 against latest (937f6fc)

🔍 Preview build

4 files changed

± 404.html
± contribute/documentation/style-guide.html
± reference/api/icalendar.cal.event.html
± _modules/icalendar/cal/event.html

angatha · 2026-06-26T04:55:58Z

-            summary: The :attr:`summary` of the event.
-            transparency: The :attr:`transparency` of the event.
+                If ``None``, this is set to the current UTC time.
+            start: Optional. The :attr:`start` of the event.


Misleading since it is not true in all cases. Please manually check the RFC.

Also, do not write Optional. That is covered by typing.

Good point. @checkzhao8888, please remove the Optional. Then this should be a small change. If you want, you can include the condition when start is required but please word it so that users understand, that they can specify it later. You may also add that this validates start <= end iff. both where specified.

If you do not want to continue with this, I will close this PR in one week.

I agree with @niccokunzmann to remove all the "Optional. "s.

niccokunzmann · 2026-07-16T14:18:47Z

@angatha, I will assign this to you. I cannot wrap my head around wether this is useful. Feel free to call in steve or close it if there is no response.

angatha · 2026-07-16T18:14:40Z

-            summary: The :attr:`summary` of the event.
-            transparency: The :attr:`transparency` of the event.
+                If ``None``, this is set to the current UTC time.
+            start: Optional. The :attr:`start` of the event.


Good point. @checkzhao8888, please remove the Optional. Then this should be a small change. If you want, you can include the condition when start is required but please word it so that users understand, that they can specify it later. You may also add that this validates start <= end iff. both where specified.

If you do not want to continue with this, I will close this PR in one week.

stevepiercy

With the suggested changes, I will approve. Thank you!

stevepiercy · 2026-07-16T21:29:35Z

-            summary: The :attr:`summary` of the event.
-            transparency: The :attr:`transparency` of the event.
+                If ``None``, this is set to the current UTC time.
+            start: Optional. The :attr:`start` of the event.


I agree with @niccokunzmann to remove all the "Optional. "s.

stevepiercy · 2026-07-16T23:22:44Z

        url: str | None = None,
    ):
-        """Create a new event with all required properties.
+        """Create a new event.


I often wonder what are the required properties, so this suggestion would help stop me from wondering. The properties are the Python representations of DTSTAMP and UID.

Suggested change

"""Create a new event.

"""Create a new event with the required properties of ``stamp`` and ``uid``.

stevepiercy · 2026-07-16T23:22:46Z

-        """Create a new event with all required properties.
+        """Create a new event.

        This creates a new Event in accordance with :rfc:`5545`.


Suggested change

This creates a new Event in accordance with :rfc:`5545`.

This creates a new ``Event`` in accordance with :rfc:`5545#section-3.6.1`.

checkzhao8888 requested review from SashankBhamidi, angatha, niccokunzmann and stevepiercy as code owners June 25, 2026 06:19

This was referenced Jun 25, 2026

docs: clarify Availability.new() optional and auto-generated properties #1505

Closed

docs: clarify Todo.new() optional and auto-generated properties #1506

Closed

docs: clarify Journal.new() and Available.new() docstrings #1507

Closed

angatha requested changes Jun 26, 2026

View reviewed changes

niccokunzmann assigned angatha Jul 16, 2026

angatha requested changes Jul 16, 2026

View reviewed changes

stevepiercy requested changes Jul 16, 2026

View reviewed changes

	"""Create a new event.
	"""Create a new event with the required properties of ``stamp`` and ``uid``.

	This creates a new Event in accordance with :rfc:`5545`.
	This creates a new ``Event`` in accordance with :rfc:`5545#section-3.6.1`.

Uh oh!

Uh oh!

Conversation

checkzhao8888 commented Jun 25, 2026

Linked issue

Description

Checklist

Uh oh!

github-actions Bot commented Jun 25, 2026

Uh oh!

read-the-docs-community Bot commented Jun 25, 2026

Documentation build overview

Uh oh!

angatha Jun 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

niccokunzmann Jun 27, 2026

Choose a reason for hiding this comment

Uh oh!

angatha Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

stevepiercy Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

niccokunzmann commented Jul 16, 2026

Uh oh!

angatha Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

stevepiercy left a comment

Choose a reason for hiding this comment

Uh oh!

stevepiercy Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

stevepiercy Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

stevepiercy Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

angatha Jun 26, 2026 •

edited

Loading