Skip to content
Closed
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
6 changes: 5 additions & 1 deletion src/icalendar/cal/alarm.py
Original file line number Diff line number Diff line change
Expand Up @@ -400,9 +400,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.
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.
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.
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 @@ -380,6 +380,7 @@ def new(
links: The :attr:`~icalendar.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.Component.refids` of the todo.
related_to: :attr:`~icalendar.Component.related_to` of the todo.
Expand Down
Loading