From d6eedf7ebf37c4671fe54024992bcdf50a7ab909 Mon Sep 17 00:00:00 2001 From: Zexi <253815666+zexi25@users.noreply.github.com> Date: Sun, 4 Oct 2026 19:27:28 -0700 Subject: [PATCH 01/15] Add type hints and docstring to Timezone._make_unique_tzname Contributes to #1072 --- src/icalendar/cal/timezone.py | 27 +++++++++++++++++++++++---- 1 file changed, 23 insertions(+), 4 deletions(-) diff --git a/src/icalendar/cal/timezone.py b/src/icalendar/cal/timezone.py index 934815e15..601f8395c 100644 --- a/src/icalendar/cal/timezone.py +++ b/src/icalendar/cal/timezone.py @@ -107,10 +107,29 @@ 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``. + + Append ``_1`` to ``tzname`` until it is not in ``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: From 025524712333e3e15417e0dcf5a4797b5bc64d4a Mon Sep 17 00:00:00 2001 From: Zexi <253815666+zexi25@users.noreply.github.com> Date: Sun, 4 Oct 2026 19:49:27 -0700 Subject: [PATCH 02/15] docs: add change log entry for #1072 --- news/1072.documentation | 1 + 1 file changed, 1 insertion(+) create mode 100644 news/1072.documentation diff --git a/news/1072.documentation b/news/1072.documentation new file mode 100644 index 000000000..aa416ae97 --- /dev/null +++ b/news/1072.documentation @@ -0,0 +1 @@ +Converted the docstring of ``Timezone._make_unique_tzname`` to Google style and added type hints. @zexi25 From adceb43e50e041056a80469b87823d5950be554e Mon Sep 17 00:00:00 2001 From: Zexi <253815666+zexi25@users.noreply.github.com> Date: Wed, 7 Oct 2026 01:34:39 -0700 Subject: [PATCH 03/15] Update src/icalendar/cal/timezone.py Co-authored-by: Nicco Kunzmann --- src/icalendar/cal/timezone.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/icalendar/cal/timezone.py b/src/icalendar/cal/timezone.py index 601f8395c..6f45f9f7a 100644 --- a/src/icalendar/cal/timezone.py +++ b/src/icalendar/cal/timezone.py @@ -110,8 +110,6 @@ def _extract_offsets(component: TimezoneDaylight | TimezoneStandard, tzname: str def _make_unique_tzname(tzname: str, tznames: set[str]) -> str: """Make a unique tzname and add it to ``tznames``. - Append ``_1`` to ``tzname`` until it is not in ``tznames``. - Parameters: tzname: The candidate timezone name. tznames: The timezone names already in use. From e0ce4b717566808cb38fabd8a2e1c8def41da958 Mon Sep 17 00:00:00 2001 From: Zexi <253815666+zexi25@users.noreply.github.com> Date: Wed, 28 Oct 2026 12:01:39 -0700 Subject: [PATCH 04/15] renamed changelog with a number suffix --- news/{1072.documentation => 1072.documentation.1} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename news/{1072.documentation => 1072.documentation.1} (100%) diff --git a/news/1072.documentation b/news/1072.documentation.1 similarity index 100% rename from news/1072.documentation rename to news/1072.documentation.1 From 256542d2c702c36b7dc2e9a5d4dede234521bf65 Mon Sep 17 00:00:00 2001 From: Zexi <253815666+zexi25@users.noreply.github.com> Date: Thu, 29 Oct 2026 11:18:46 -0700 Subject: [PATCH 05/15] Rename to 1072.documentation.2 --- news/{1072.documentation.1 => 1072.documentation.2} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename news/{1072.documentation.1 => 1072.documentation.2} (100%) diff --git a/news/1072.documentation.1 b/news/1072.documentation.2 similarity index 100% rename from news/1072.documentation.1 rename to news/1072.documentation.2 From 916334ae1d8531247d2242ef5cb071729165afa0 Mon Sep 17 00:00:00 2001 From: Zexi <253815666+zexi25@users.noreply.github.com> Date: Thu, 29 Oct 2026 11:31:34 -0700 Subject: [PATCH 06/15] modified docstring for to_tz method to google style --- src/icalendar/cal/timezone.py | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/src/icalendar/cal/timezone.py b/src/icalendar/cal/timezone.py index 840f28385..4e916cd01 100644 --- a/src/icalendar/cal/timezone.py +++ b/src/icalendar/cal/timezone.py @@ -163,12 +163,16 @@ def _make_unique_tzname(tzname: str, tznames: set[str]) -> str: 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. + 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) From e2d2ab84506da2ca46c9e13af2966242966daa8d Mon Sep 17 00:00:00 2001 From: Zexi <253815666+zexi25@users.noreply.github.com> Date: Thu, 29 Oct 2026 11:41:48 -0700 Subject: [PATCH 07/15] Changed docstring of from_tzid to google style --- src/icalendar/cal/timezone.py | 35 +++++++++++++++++++++-------------- 1 file changed, 21 insertions(+), 14 deletions(-) diff --git a/src/icalendar/cal/timezone.py b/src/icalendar/cal/timezone.py index 4e916cd01..2b0d7168c 100644 --- a/src/icalendar/cal/timezone.py +++ b/src/icalendar/cal/timezone.py @@ -386,21 +386,28 @@ def from_tzid( ) -> 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 + 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. - .. note:: + 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. """ tz = tzp.timezone(tzid) From 29217f090c24193ba1bbb301f08d28d761328111 Mon Sep 17 00:00:00 2001 From: Zexi <253815666+zexi25@users.noreply.github.com> Date: Thu, 29 Oct 2026 11:44:51 -0700 Subject: [PATCH 08/15] Add note directive in timezone.py documentation --- src/icalendar/cal/timezone.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/icalendar/cal/timezone.py b/src/icalendar/cal/timezone.py index 2b0d7168c..ac57a4ef0 100644 --- a/src/icalendar/cal/timezone.py +++ b/src/icalendar/cal/timezone.py @@ -407,7 +407,7 @@ def from_tzid( BEGIN:VTIMEZONE TZID:Europe/Berlin - Note: + .. note:: This can take some time. Please cache the results. """ tz = tzp.timezone(tzid) From 84da3d99329f22c727cec95443517c4db2e1a153 Mon Sep 17 00:00:00 2001 From: Zexi <253815666+zexi25@users.noreply.github.com> Date: Thu, 29 Oct 2026 11:49:50 -0700 Subject: [PATCH 09/15] Update 1072.documentation.2 --- news/1072.documentation.2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/news/1072.documentation.2 b/news/1072.documentation.2 index aa416ae97..898425d85 100644 --- a/news/1072.documentation.2 +++ b/news/1072.documentation.2 @@ -1 +1 @@ -Converted the docstring of ``Timezone._make_unique_tzname`` to Google style and added type hints. @zexi25 +Converted the docstring of ``Timezone._make_unique_tzname``, ``Timezone.to_tz``, ``Timezone.from_tzid`` to Google style and added type hints. I used claude Opus5.5 for wording and checked the results. @zexi25 From 442dd8300781404ac5d508e2e56de3370e6e0395 Mon Sep 17 00:00:00 2001 From: Zexi <253815666+zexi25@users.noreply.github.com> Date: Thu, 29 Oct 2026 11:58:36 -0700 Subject: [PATCH 10/15] Clean up whitespace in timezone.py Removed unnecessary whitespace in timezone.py --- src/icalendar/cal/timezone.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/icalendar/cal/timezone.py b/src/icalendar/cal/timezone.py index ac57a4ef0..476b12c6d 100644 --- a/src/icalendar/cal/timezone.py +++ b/src/icalendar/cal/timezone.py @@ -397,10 +397,10 @@ def from_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]) From 97599dfa7207d51c4306494778343570738cc2f0 Mon Sep 17 00:00:00 2001 From: Zexi <253815666+zexi25@users.noreply.github.com> Date: Thu, 12 Nov 2026 16:47:29 -0800 Subject: [PATCH 11/15] Update news/1072.documentation.2 Co-authored-by: Steve Piercy --- news/1072.documentation.2 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/news/1072.documentation.2 b/news/1072.documentation.2 index 898425d85..d592fb363 100644 --- a/news/1072.documentation.2 +++ b/news/1072.documentation.2 @@ -1 +1 @@ -Converted the docstring of ``Timezone._make_unique_tzname``, ``Timezone.to_tz``, ``Timezone.from_tzid`` to Google style and added type hints. I used claude Opus5.5 for wording and checked the results. @zexi25 +Converted the docstring of ``Timezone._make_unique_tzname``, :meth:`Timezone.to_tz `, :meth:`Timezone.from_tzid Date: Thu, 12 Nov 2026 16:48:05 -0800 Subject: [PATCH 12/15] Update src/icalendar/cal/timezone.py Co-authored-by: Steve Piercy --- src/icalendar/cal/timezone.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/icalendar/cal/timezone.py b/src/icalendar/cal/timezone.py index 476b12c6d..6cafcfb11 100644 --- a/src/icalendar/cal/timezone.py +++ b/src/icalendar/cal/timezone.py @@ -161,7 +161,7 @@ def _make_unique_tzname(tzname: str, tznames: set[str]) -> str: return tzname def to_tz(self, tzp: TZP = tzp, lookup_tzid: bool = True): - """convert this VTIMEZONE component to a timezone object + """Convert this VTIMEZONE component to a timezone object. Parameters: tzp: Timezone provider to use. From 02dfa7e05a412902f51fb18a46046b2d20f580e5 Mon Sep 17 00:00:00 2001 From: Zexi <253815666+zexi25@users.noreply.github.com> Date: Thu, 12 Nov 2026 16:48:51 -0800 Subject: [PATCH 13/15] Update src/icalendar/cal/timezone.py Co-authored-by: Steve Piercy --- src/icalendar/cal/timezone.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/icalendar/cal/timezone.py b/src/icalendar/cal/timezone.py index 6cafcfb11..b2ec4c2b9 100644 --- a/src/icalendar/cal/timezone.py +++ b/src/icalendar/cal/timezone.py @@ -384,7 +384,7 @@ 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"``. + """Create a VTIMEZONE from a tzid, such as ``"Europe/Berlin"``. Parameters: tzid: The id of the timezone. From 233b6ba69f5b22170c05bd984ce425a2371fe650 Mon Sep 17 00:00:00 2001 From: Zexi <253815666+zexi25@users.noreply.github.com> Date: Thu, 12 Nov 2026 16:49:04 -0800 Subject: [PATCH 14/15] Update src/icalendar/cal/timezone.py Co-authored-by: Steve Piercy --- src/icalendar/cal/timezone.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/icalendar/cal/timezone.py b/src/icalendar/cal/timezone.py index b2ec4c2b9..68b6e9b81 100644 --- a/src/icalendar/cal/timezone.py +++ b/src/icalendar/cal/timezone.py @@ -387,7 +387,7 @@ def from_tzid( """Create a VTIMEZONE from a tzid, such as ``"Europe/Berlin"``. Parameters: - tzid: The id of the timezone. + 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. From ce66196181288b89f4cf1a3bf92c3409879f8124 Mon Sep 17 00:00:00 2001 From: Zexi <253815666+zexi25@users.noreply.github.com> Date: Thu, 12 Nov 2026 17:10:04 -0800 Subject: [PATCH 15/15] update doc file suffix to 4 --- news/{1072.documentation.2 => 1072.documentation.4} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename news/{1072.documentation.2 => 1072.documentation.4} (100%) diff --git a/news/1072.documentation.2 b/news/1072.documentation.4 similarity index 100% rename from news/1072.documentation.2 rename to news/1072.documentation.4