Skip to content

docs: clarify new() docstrings of Alarm, Availability, Available and Todo - #1805

Open
sandeep780049 wants to merge 1 commit into
PyCalendar:mainfrom
sandeep780049:docstring-new-1473
Open

sandeep780049 wants to merge 1 commit into
PyCalendar:mainfrom
sandeep780049:docstring-new-1473

Conversation

@sandeep780049

Copy link
Copy Markdown
Contributor

Note: Supersedes #1800, which can no longer be reopened because the head fork was deleted. These are the exact same commits (head SHA a079d2b), unchanged. Apologies for my earlier comment about the bot notice — I misread the situation, and thanks @stevepiercy for double-checking the bot summary.

Linked issue

Description

Audited the constructor docstrings of the unchecked components against the implementation and the applicable RFCs, and corrected the inaccuracies found: a wrong component type in one, three missing parameters, one required argument now documented as required, and one overstated claim removed. One file verified accurate and unchanged. Change log fragment included; Responsible AI use disclosed in the commit message.

Checklist

  • I added a change log entry, following the instructions in all subsections under Change log requirements.
  • I followed icalendar's Artificial intelligence policy and disclosed my Responsible AI use in my commit messages, if applicable.
  • I added or updated tests, if applicable.
  • I ran and ensured all tests pass locally by following Run tests.
  • I added or edited documentation as necessary, both as docstrings to be rendered in the API documentation and narrative documentation, following the Style guide.

@github-actions

Copy link
Copy Markdown
Contributor

This pull request did not pass quality checks and AI use is suspected. Please review Contribute and make any necessary amendments.

@github-actions github-actions Bot added the ai-suspicion This contribution is possibly created with lots of AI help without enough human understanding. label Sep 17, 2026
@github-actions

Copy link
Copy Markdown
Contributor

Profile summary:

GitHub user: sandeep780049
🟢 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 sandeep780049`.
Full profile
GitHub user: sandeep780049
🟢 No concerns found with user's profile.
   🟢 Account age: 1 year, 1 month
   🟢 Profile information:
        name: Sandeep yadav
        location: India
        bio: Python, java devloper
      Empty fields: company, blog, email

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

   🟢 2 of 12 external PRs closed without merging in the last 21 days.

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

   🟢 0 external issues closed as NOT_PLANNED.
   🟢 0 external issues opened with the same title.

@coveralls-official

coveralls-official Bot commented Sep 17, 2026 •

Copy link
Copy Markdown

Coverage Status

coverage: 97.906%. remained the same — sandeep780049:docstring-new-1473 into collective:main

@sandeep780049

Copy link
Copy Markdown
Contributor Author

Hi! I've read the AI policy in the contribution guide and want to make sure this PR is fully compliant, since it was flagged as suspected AI use.

To be transparent: I used AI assistance to draft this change. It is docs-only — clarifying the new() docstrings of Alarm, Availability, Available and Todo so the parameters and return types are easier to understand.

From the policy, I understand AI-assisted PRs should have:

  1. A corresponding issue opened first,
  2. The AI model and usage disclosed in the commit messages, and
  3. An AI-use disclosure in the changelog entry.

I take full responsibility for this change: I reviewed every docstring edit for accuracy against the actual behavior, and CI is green on this PR.

Could a maintainer confirm what's needed to proceed? I'm happy to open the backing issue, push an amended commit with the model/usage disclosure in the message, and add the changelog disclosure — whatever is most useful.

@sandeep780049

Copy link
Copy Markdown
Contributor Author

Friendly ping for review when you have a moment — small docs-only change clarifying the new() docstrings (no behavior change). Happy to adjust wording if anything reads off.

@sandeep780049

Copy link
Copy Markdown
Contributor Author

Rebased this onto current master so the branch is clean again; the docs-only changes are unchanged. Docs readers can stop when they see the previously seen lines.

@niccokunzmann niccokunzmann left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for the PR! The docs changes are fine with me. Could you adjust the changelog?

Comment thread news/1473.documentation
@@ -0,0 +1 @@
Clarified the ``new()`` docstrings of the calendar components: Availability.new no longer calls itself an event, previously undocumented parameters are now listed, Available.new documents its required start, and Alarm.new points to the action-specific constructors. Verified the docstring grammar against RFC 5545 and RFC 7953. AI-assisted: Claude was used to audit the docstrings against the RFCs and draft the wording. The final change was manually verified. @sandeep780049

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is rst and copied into the changelog - can you have a look and make it consistent with the other entries by using links to the methods and classes?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reduce verbosity and link to the methods, per the linked guidance.

Suggested change
Clarified the ``new()`` docstrings of the calendar components: Availability.new no longer calls itself an event, previously undocumented parameters are now listed, Available.new documents its required start, and Alarm.new points to the action-specific constructors. Verified the docstring grammar against RFC 5545 and RFC 7953. AI-assisted: Claude was used to audit the docstrings against the RFCs and draft the wording. The final change was manually verified. @sandeep780049
Clarified the docstrings of the calendar components :meth:`Availability.new <icalendar.cal.availability.Availability.new>`, :meth:`Available.new <icalendar.cal.available.Available.new>`, and :meth:`Alarm.new <icalendar.cal.alarm.Alarm.new>`. AI-assisted: Claude was used to audit the docstrings against the RFCs and draft the wording. The final change was manually verified. @sandeep780049

Comment on lines 407 to +411
This creates a new Alarm in accordance with :rfc:`5545`.
Note that :attr:`ACTION` and :attr:`TRIGGER` are required in a
conforming VALARM, but are not set by this method.
Use :meth:`new_display`, :meth:`new_audio` or :meth:`new_email`
to create a valid alarm.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this method is not in accordance with the RFC. As I interpret the RFC, an alarm must have at least one of (audioprop / dispprop / emailprop) per https://datatracker.ietf.org/doc/html/rfc5545.html#section-3.6.6. It doesn't make sense to have an alarm without at least one kind of notification.

@niccokunzmann how do you want to handle this from a design perspective? Each of the properties has different requirements, and none are validated in accordance the RFC. Is there an issue or pull request that describes what is needed for conformance?

Suggested change
This creates a new Alarm in accordance with :rfc:`5545`.
Note that :attr:`ACTION` and :attr:`TRIGGER` are required in a
conforming VALARM, but are not set by this method.
Use :meth:`new_display`, :meth:`new_audio` or :meth:`new_email`
to create a valid alarm.
This new Alarm partially conforms with :rfc:`5545#section-3.6.6`.
It requires both an ACTION and TRIGGER property. It doesn't require
a DESCRIPTION property when the ACTION is either DISPLAY or EMAIL.
It doesn't require a SUMMARY property when the ACTION is EMAIL.
Use :meth:`new_display`, :meth:`new_audio` or
:meth:`new_email` to create a valid Alarm.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@niccokunzmann we need your guidance for this one.

uid: str | uuid.UUID | None = None,
) -> Self:
"""Create a new alarm with all required properties.
"""Create a new alarm with the given properties.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
"""Create a new alarm with the given properties.
"""Create a new Alarm with the given properties.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This needs to be addressed.

Comment on lines +149 to +150
start: Required. The :attr:`start` of the Available component.
If ``None``, an :class:`~icalendar.error.InvalidCalendar` is raised.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There's an inconsistency between the type hint for start, its implementation, and its docstring. The implementation requires a datetime with a timezone, but the class accepts None for start. I think we should we remove None = None from start's' type hint and adjust this docstring accordingly. What do you think?

@niccokunzmann do you have an opinion here?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@niccokunzmann still need your opinion for this one, too.

@stevepiercy

Copy link
Copy Markdown
Member

@sandeep780049 it's been two weeks since @niccokunzmann requested that you update your PR. We'll close abandoned PRs.

@stevepiercy

Copy link
Copy Markdown
Member

@sandeep780049 would you like to complete work on this PR? Do you need anything from us? Please let us know. Thank you!

…Todo

Fixes parts of PyCalendar#1473: Availability.new no longer describes itself as an event, previously undocumented parameters are now documented, Available.new documents its required start, and Alarm.new points to the action-specific constructors. Adds a news fragment.

Responsible AI use: Claude was used to audit the docstrings against RFC 5545 and RFC 7953 and draft the wording. The final change was manually verified.
@sandeep780049

Copy link
Copy Markdown
Contributor Author

Thanks @stevepiercy and @niccokunzmann — pushed an update addressing the review:

  • news/1473.documentation now uses the same RST cross-reference style as the other fragments (full :meth: / :class: targets instead of bare prose).
  • Alarm.new docstring now uses the wording you suggested, references :rfc:5545#section-3.6.6, and links to new_display / new_audio / new_email.
  • Available.new / start: I kept datetime | None = None. The timezone check only runs when cls._validate_new is enabled, so None is a legal runtime value and dropping it from the annotation would make the type hint disagree with the implementation. I tightened the docstring instead: a conforming Available needs a timezone-aware datetime, and InvalidCalendar is raised when validation is enabled. If you'd prefer start to be genuinely required, that's a behaviour change and I can do it as a follow-up PR so this one stays documentation-only.
  • Rebased onto main (the branch previously had merge commits). pytest -k "alarm or available or availability or todo" → 1382 passed, 24 xfailed.

Happy to adjust anything else.

@stevepiercy stevepiercy left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@sandeep780049 would you please address the missed item?

@niccokunzmann we need your feedback on a couple of items in this PR. Thank you!

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ai-suspicion This contribution is possibly created with lots of AI help without enough human understanding.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants