Repository navigation
docs: clarify new() docstrings of Alarm, Availability, Available and Todo #1805
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 | ||
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -407,9 +407,13 @@ def new( | |||||||||||||||||||||||
| summary: str | None = None, | ||||||||||||||||||||||||
| uid: str | uuid.UUID | None = None, | ||||||||||||||||||||||||
| ) -> Self: | ||||||||||||||||||||||||
| """Create a new alarm with all required properties. | ||||||||||||||||||||||||
| """Create a new alarm with the given properties. | ||||||||||||||||||||||||
|
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This needs to be addressed. |
||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| 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. | ||||||||||||||||||||||||
|
Comment on lines
412
to
+416
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @niccokunzmann we need your guidance for this one. |
||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Parameters: | ||||||||||||||||||||||||
| action: The :attr:`ACTION` of the alarm. Typical values are | ||||||||||||||||||||||||
|
|
||||||||||||||||||||||||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -146,10 +146,11 @@ def new( | |
| sequence: The :attr:`sequence` of the Available component. | ||
| stamp: The :attr:`~icalendar.cal.component.Component.stamp` of the Available component. | ||
| If None, this is set to the current time. | ||
| start: The :attr:`start` of the Available component. | ||
| start: Required. The :attr:`start` of the Available component. | ||
| If ``None``, an :class:`~icalendar.error.InvalidCalendar` is raised. | ||
|
Comment on lines
+149
to
+150
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. There's an inconsistency between the type hint for @niccokunzmann do you have an opinion here?
Member
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. @niccokunzmann still need your opinion for this one, too. |
||
| summary: The :attr:`summary` of the Available component. | ||
| uid: The :attr:`uid` of the Available component. | ||
| If None, this is set to a new :func:`uuid.uuid4`. | ||
| If ``None``, this is set to a new :func:`uuid.uuid4`. | ||
|
|
||
| Returns: | ||
| :class:`Available` | ||
|
|
||
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
See guidance at https://icalendar.readthedocs.io/en/latest/contribute/documentation/style-guide.html#markup-examples and https://icalendar.readthedocs.io/en/latest/contribute/documentation/style-guide.html#cross-reference-python-objects.
There was a problem hiding this comment.
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.