Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions news/1473.documentation
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

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

6 changes: 5 additions & 1 deletion src/icalendar/cal/alarm.py
Original file line number Diff line number Diff line change
Expand Up @@ -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.

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.


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

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.


Parameters:
action: The :attr:`ACTION` of the alarm. Typical values are
Expand Down
6 changes: 5 additions & 1 deletion src/icalendar/cal/availability.py
Original file line number Diff line number Diff line change
Expand Up @@ -264,7 +264,7 @@ def new(
uid: str | uuid.UUID | None = None,
url: str | None = None,
) -> Self:
"""Create a new event with all required properties.
"""Create a new Availability with all required properties.

This creates a new Availability in accordance with :rfc:`7953`.

Expand All @@ -273,6 +273,9 @@ def new(
categories: The :attr:`categories` of the availability.
classification: The :attr:`classification` of the availability.
comments: The :attr:`~icalendar.cal.component.Component.comments` of the availability.
components: The :attr:`~icalendar.cal.component.Component.subcomponents`
of the availability, usually :class:`~icalendar.cal.available.Available`
components.
concepts: The :attr:`~icalendar.cal.component.Component.concepts` of the availability.
contacts: The :attr:`contacts` of the availability.
created: The :attr:`~icalendar.cal.component.Component.created` of the availability.
Expand All @@ -283,6 +286,7 @@ def new(
links: The :attr:`~icalendar.cal.component.Component.links` of the availability.
location: The :attr:`location` of the availability.
organizer: The :attr:`organizer` of the availability.
priority: The :attr:`priority` of the availability.
refids: :attr:`~icalendar.cal.component.Component.refids` of the availability.
related_to: :attr:`~icalendar.cal.component.Component.related_to` of the availability.
sequence: The :attr:`sequence` of the availability.
Expand Down
5 changes: 3 additions & 2 deletions src/icalendar/cal/available.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

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.

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`
Expand Down
1 change: 1 addition & 0 deletions src/icalendar/cal/todo.py
Original file line number Diff line number Diff line change
Expand Up @@ -402,6 +402,7 @@ def new(
links: The :attr:`~icalendar.cal.component.Component.links` of the todo.
location: The :attr:`location` of the todo.
organizer: The :attr:`organizer` of the todo.
priority: The :attr:`priority` of the todo.
recurrence_id: The :attr:`RECURRENCE_ID` of the todo.
refids: :attr:`~icalendar.cal.component.Component.refids` of the todo.
related_to: :attr:`~icalendar.cal.component.Component.related_to` of the todo.
Expand Down