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
3 changes: 3 additions & 0 deletions docs/contribute/documentation/style-guide.rst
Original file line number Diff line number Diff line change
Expand Up @@ -352,6 +352,9 @@ The following docstrings items are the most frequently used in icalendar, althou
Summary
Docstrings must begin with a one-line summary of the Python object, terminated by a period.

Private flag
Use `:meta private: <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#marking-objects-as-public-or-private>`_ after the summary for "private" or :ref:`internal-use-only` methods.

Description
When the one-line summary is insufficient to describe the Python object, then write an overall description of what it does, without going into details of how it does it.
Leave implementation details to the code, and optionally inline code comments.
Expand Down
1 change: 1 addition & 0 deletions news/1711.documentation
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
Documented and standardize "private" or "internal use only" methods with Sphinx ``:meta private:`` field flag. :user:`stevepiercy`
53 changes: 35 additions & 18 deletions src/icalendar/alarms.py
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,17 @@ class AlarmTime:
An AlarmTime instance combines an alarm component with its resolved
trigger time and additional state information, such as acknowledgment
and snoozing.

Create an instance of ``AlarmTime`` with any of its parameters.

Parameters:
alarm: Required. The underlying alarm component.
trigger: Required. A date or datetime at which to trigger the alarm.
acknowledged_until: Optional datetime in UTC until which
the alarm has been acknowledged.
parent: Optional parent component to which the alarm refers.
snoozed_until: Optional datetime in UTC until which
the alarm has been snoozed.
"""

def __init__(
Expand All @@ -54,17 +65,6 @@ def __init__(
snoozed_until: datetime | None = None,
parent: Parent | None = None,
) -> None:
"""Create an instance of ``AlarmTime`` with any of its parameters.

Parameters:
alarm: The underlying alarm component.
trigger: A date or datetime at which to trigger the alarm.
acknowledged_until: Optional datetime in UTC until which
the alarm has been acknowledged.
snoozed_until: Optional datetime in UTC until which
the alarm has been snoozed.
parent: Optional parent component to which the alarm refers.
"""
self._alarm = alarm
self._parent = parent
self._trigger = trigger
Expand Down Expand Up @@ -230,7 +230,6 @@ class Alarms:
"""

def __init__(self, component: Alarm | Event | Todo | None = None) -> None:
"""Start computing alarm times."""
self._absolute_alarms: list[Alarm] = []
self._start_alarms: list[Alarm] = []
self._end_alarms: list[Alarm] = []
Expand Down Expand Up @@ -308,7 +307,10 @@ def _add(self, dt: datetime, td: timedelta) -> datetime: ...
def _add(self, dt: date, td: timedelta) -> date: ...

def _add(self, dt: date, td: timedelta) -> date | datetime:
"""Add a timedelta to a datetime."""
"""Add a timedelta to a datetime.

:meta private:
"""
if is_date(dt):
if td.seconds == 0:
return dt + td
Expand Down Expand Up @@ -369,7 +371,10 @@ def times(self) -> list[AlarmTime]:
)

def _repeat(self, first: datetime, alarm: Alarm) -> Generator[datetime]:
"""The times when the alarm is triggered relative to start."""
"""The times when the alarm is triggered relative to start.

:meta private:
"""
yield first # we trigger at the start
repeat = alarm.repeat
duration = alarm.DURATION
Expand All @@ -378,23 +383,32 @@ def _repeat(self, first: datetime, alarm: Alarm) -> Generator[datetime]:
yield self._add(first, duration * i)

def _alarm_time(self, alarm: Alarm, trigger: date) -> AlarmTime:
"""Create an alarm time with the additional attributes."""
"""Create an alarm time with the additional attributes.

:meta private:
"""
if getattr(trigger, "tzinfo", None) is None and self._local_tzinfo is not None:
trigger = normalize_pytz(trigger.replace(tzinfo=self._local_tzinfo))
return AlarmTime(
alarm, trigger, self._last_ack, self._snooze_until, self._parent
)

def _get_absolute_alarm_times(self) -> list[AlarmTime]:
"""Return a list of absolute alarm times."""
"""Return a list of absolute alarm times.

:meta private:
"""
return [
self._alarm_time(alarm, trigger)
for alarm in self._absolute_alarms
for trigger in self._repeat(alarm.TRIGGER, alarm)
]

def _get_start_alarm_times(self) -> list[AlarmTime]:
"""Return a list of alarm times relative to the start of the component."""
"""Return a list of alarm times relative to the start of the component.

:meta private:
"""
if self._start is None and self._start_alarms:
raise ComponentStartMissing(
"Use Alarms.set_start because at least one alarm is relative to the "
Expand All @@ -407,7 +421,10 @@ def _get_start_alarm_times(self) -> list[AlarmTime]:
]

def _get_end_alarm_times(self) -> list[AlarmTime]:
"""Return a list of alarm times relative to the end of the component."""
"""Return a list of alarm times relative to the end of the component.

:meta private:
"""
if self._end is None and self._end_alarms:
raise ComponentEndMissing(
"Use Alarms.set_end because at least one alarm is relative to the end "
Expand Down
Loading