Add type hints and docstring to Timezone._make_unique_tzname

news/1072.documentation.4

@@ -0,0 +1 @@
+Converted the docstring of ``Timezone._make_unique_tzname``, :meth:`Timezone.to_tz <icalendar.cal.timezone.Timezone.to_tz>`, :meth:`Timezone.from_tzid <icalendar.cal.timezone.Timezone.from_tzid` to Google style and added type hints. I used claude Opus5.5 for wording and checked the results. @zexi25

src/icalendar/cal/timezone.py

@@ -132,10 +132,27 @@ def _extract_offsets(component: TimezoneDaylight | TimezoneStandard, tzname: str
         return is_dst, transitions
 
     @staticmethod
-    def _make_unique_tzname(tzname, tznames):
-        """
-        :param tzname: Candidate tzname
-        :param tznames: Other tznames
+    def _make_unique_tzname(tzname: str, tznames: set[str]) -> str:
+        """Make a unique tzname and add it to ``tznames``.
+
+        Parameters:
+            tzname: The candidate timezone name.
+            tznames: The timezone names already in use.
+
+        Returns:
+            The unique timezone name.
+
+        Example:
+            .. code-block:: pycon
+
+                >>> from icalendar import Timezone
+                >>> names = {"EST"}
+                >>> Timezone._make_unique_tzname("EST", names)
+                'EST_1'
+                >>> Timezone._make_unique_tzname("EST", names)
+                'EST_1_1'
+                >>> sorted(names)
+                ['EST', 'EST_1', 'EST_1_1']
         """
         # TODO better way of making sure tznames are unique
         while tzname in tznames:
@@ -144,14 +161,18 @@ def _make_unique_tzname(tzname, tznames):
         return tzname
 
     def to_tz(self, tzp: TZP = tzp, lookup_tzid: bool = True):
-        """convert this VTIMEZONE component to a timezone object
-
-        :param tzp: timezone provider to use
-        :param lookup_tzid: whether to use the TZID property to look up existing
-                            timezone definitions with tzp.
-                            If it is False, a new timezone will be created.
-                            If it is True, the existing timezone will be used
-                            if it exists, otherwise a new timezone will be created.
+        """Convert this VTIMEZONE component to a timezone object.
+
+        Parameters:
+            tzp: Timezone provider to use.
+            lookup_tzid: Whether to use the TZID property to look up existing
+                timezone definitions with ``tzp``. If ``True``, the existing
+                timezone is used if it exists; otherwise a new timezone is
+                created. If ``False``, a new timezone is always created.
+
+        Returns:
+            A timezone object, either looked up from ``tzp`` or newly created
+            from this component.
         """
         if lookup_tzid:
             tz = tzp.timezone(self.tz_name)
@@ -363,21 +384,28 @@ def from_tzid(
         first_date: date = DEFAULT_FIRST_DATE,
         last_date: date = DEFAULT_LAST_DATE,
     ) -> Timezone:
-        """Create a VTIMEZONE from a tzid like ``"Europe/Berlin"``.
-
-        :param tzid: the id of the timezone
-        :param tzp: the timezone provider
-        :param first_date: a datetime that is earlier than anything
-            that happens in the calendar
-        :param last_date: a datetime that is later than anything
-            that happens in the calendar
-        :raises ValueError: If the tzid is unknown.
-
-        >>> from icalendar import Timezone
-        >>> tz = Timezone.from_tzid("Europe/Berlin")
-        >>> print(tz.to_ical()[:36])
-        BEGIN:VTIMEZONE
-        TZID:Europe/Berlin
+        """Create a VTIMEZONE from a tzid, such as ``"Europe/Berlin"``.
+
+        Parameters:
+            tzid: The ID of the timezone.
+            tzp: The timezone provider.
+            first_date: A date that is earlier than anything that happens in the calendar.
+            last_date: A date that is later than anything that happens in the calendar.
+
+        Returns:
+            A VTIMEZONE component for the given tzid.
+
+        Raises:
+            ValueError: If the tzid is unknown.
+
+        Example:
+            .. code-block:: pycon
+
+                >>> from icalendar import Timezone
+                >>> tz = Timezone.from_tzid("Europe/Berlin")
+                >>> print(tz.to_ical()[:36])
+                BEGIN:VTIMEZONE
+                TZID:Europe/Berlin
 
         .. note::
             This can take some time. Please cache the results.