Skip to content

Commit a079d2b

Browse files
committed
docs: clarify new() docstrings of Alarm, Availability, Available and Todo
Fixes parts of #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.
1 parent c953584 commit a079d2b

5 files changed

Lines changed: 15 additions & 4 deletions

File tree

‎news/1473.documentation‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
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

‎src/icalendar/cal/alarm.py‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -400,9 +400,13 @@ def new(
400400
summary: str | None = None,
401401
uid: str | uuid.UUID | None = None,
402402
) -> Self:
403-
"""Create a new alarm with all required properties.
403+
"""Create a new alarm with the given properties.
404404
405405
This creates a new Alarm in accordance with :rfc:`5545`.
406+
Note that :attr:`ACTION` and :attr:`TRIGGER` are required in a
407+
conforming VALARM, but are not set by this method.
408+
Use :meth:`new_display`, :meth:`new_audio` or :meth:`new_email`
409+
to create a valid alarm.
406410
407411
Parameters:
408412
action: The :attr:`ACTION` of the alarm. Typical values are

‎src/icalendar/cal/availability.py‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -264,7 +264,7 @@ def new(
264264
uid: str | uuid.UUID | None = None,
265265
url: str | None = None,
266266
) -> Self:
267-
"""Create a new event with all required properties.
267+
"""Create a new Availability with all required properties.
268268
269269
This creates a new Availability in accordance with :rfc:`7953`.
270270
@@ -273,6 +273,9 @@ def new(
273273
categories: The :attr:`categories` of the availability.
274274
classification: The :attr:`classification` of the availability.
275275
comments: The :attr:`~icalendar.cal.component.Component.comments` of the availability.
276+
components: The :attr:`~icalendar.cal.component.Component.subcomponents`
277+
of the availability, usually :class:`~icalendar.cal.available.Available`
278+
components.
276279
concepts: The :attr:`~icalendar.cal.component.Component.concepts` of the availability.
277280
contacts: The :attr:`contacts` of the availability.
278281
created: The :attr:`~icalendar.cal.component.Component.created` of the availability.
@@ -283,6 +286,7 @@ def new(
283286
links: The :attr:`~icalendar.cal.component.Component.links` of the availability.
284287
location: The :attr:`location` of the availability.
285288
organizer: The :attr:`organizer` of the availability.
289+
priority: The :attr:`priority` of the availability.
286290
refids: :attr:`~icalendar.cal.component.Component.refids` of the availability.
287291
related_to: :attr:`~icalendar.cal.component.Component.related_to` of the availability.
288292
sequence: The :attr:`sequence` of the availability.

‎src/icalendar/cal/available.py‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -146,10 +146,11 @@ def new(
146146
sequence: The :attr:`sequence` of the Available component.
147147
stamp: The :attr:`~icalendar.cal.component.Component.stamp` of the Available component.
148148
If None, this is set to the current time.
149-
start: The :attr:`start` of the Available component.
149+
start: Required. The :attr:`start` of the Available component.
150+
If ``None``, an :class:`~icalendar.error.InvalidCalendar` is raised.
150151
summary: The :attr:`summary` of the Available component.
151152
uid: The :attr:`uid` of the Available component.
152-
If None, this is set to a new :func:`uuid.uuid4`.
153+
If ``None``, this is set to a new :func:`uuid.uuid4`.
153154
154155
Returns:
155156
:class:`Available`

‎src/icalendar/cal/todo.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -380,6 +380,7 @@ def new(
380380
links: The :attr:`~icalendar.Component.links` of the todo.
381381
location: The :attr:`location` of the todo.
382382
organizer: The :attr:`organizer` of the todo.
383+
priority: The :attr:`priority` of the todo.
383384
recurrence_id: The :attr:`RECURRENCE_ID` of the todo.
384385
refids: :attr:`~icalendar.Component.refids` of the todo.
385386
related_to: :attr:`~icalendar.Component.related_to` of the todo.

0 commit comments

Comments
 (0)