From 16694d43d3381e33c25aca67eb7eaf0a46cb9d77 Mon Sep 17 00:00:00 2001 From: Georeth Zhou Date: Mon, 14 Nov 2022 18:53:03 +0800 Subject: [PATCH 1/4] DOC: mention tz_convert(None) and tz_localize(None) for dataframe or series --- pandas/core/generic.py | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 969dcde9d792e..17453058b50f5 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -10137,9 +10137,13 @@ def tz_convert( """ Convert tz-aware axis to target time zone. + To convert to UTC and get a tz-naive axis, pass tz=None. + Parameters ---------- - tz : str or tzinfo object + tz : str or tzinfo object or None + Time zone to convert index to. Passing ``None`` will convert to + UTC and remove the timezone information. axis : the axis to convert level : int, str, default None If axis is a MultiIndex, convert a specific level. Otherwise @@ -10204,9 +10208,14 @@ def tz_localize( This operation localizes the Index. To localize the values in a timezone-naive Series, use :meth:`Series.dt.tz_localize`. + This method can also used to do the inverse -- to get a tz-naive index + from a time zone aware index, pass tz=None. + Parameters ---------- - tz : str or tzinfo + tz : str or tzinfo or None + Time zone to convert the index to. pass ``None`` will remove the + time zone information and preserve local time. axis : the axis to localize level : int, str, default None If axis ia a MultiIndex, localize a specific level. Otherwise From 70094e38d888845aa1eb209f1df28d2a9ea13bca Mon Sep 17 00:00:00 2001 From: Georeth Zhou Date: Fri, 18 Nov 2022 18:16:41 +0800 Subject: [PATCH 2/4] DOC: remove function-level doc of tz_convert(None) and tz_localize(None) --- pandas/core/generic.py | 5 ----- 1 file changed, 5 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 17453058b50f5..22f858efeb4e8 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -10137,8 +10137,6 @@ def tz_convert( """ Convert tz-aware axis to target time zone. - To convert to UTC and get a tz-naive axis, pass tz=None. - Parameters ---------- tz : str or tzinfo object or None @@ -10208,9 +10206,6 @@ def tz_localize( This operation localizes the Index. To localize the values in a timezone-naive Series, use :meth:`Series.dt.tz_localize`. - This method can also used to do the inverse -- to get a tz-naive index - from a time zone aware index, pass tz=None. - Parameters ---------- tz : str or tzinfo or None From ca4fcdc4e621c7c28acac46e7c0ce57ae63651fc Mon Sep 17 00:00:00 2001 From: Georeth Zhou Date: Fri, 18 Nov 2022 18:34:41 +0800 Subject: [PATCH 3/4] DOC: add example for tz_convert and tz_localize --- pandas/core/generic.py | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 22f858efeb4e8..1d2b06e0596e6 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -10158,6 +10158,24 @@ def tz_convert( ------ TypeError If the axis is tz-naive. + + Examples + -------- + Change to another time zone: + + >>> s = pd.Series([1], + ... index=pd.DatetimeIndex(['2018-09-15 01:30:00+02:00'])) + >>> s.tz_convert('Asia/Shanghai') + 2018-09-15 07:30:00+08:00 1 + dtype: int64 + + Convert to UTC and get a tz-naive index: + + >>> s = pd.Series([1], + ... index=pd.DatetimeIndex(['2018-09-15 01:30:00+02:00'])) + >>> s.tz_convert(None) + 2018-09-14 23:30:00 1 + dtype: int64 """ axis = self._get_axis_number(axis) ax = self._get_axis(axis) @@ -10266,6 +10284,14 @@ def tz_localize( 2018-09-15 01:30:00+02:00 1 dtype: int64 + Convert to tz-naive index and preserve local time: + + >>> s = pd.Series([1], + ... index=pd.DatetimeIndex(['2018-09-15 01:30:00+02:00'])) + >>> s.tz_localize(None) + 2018-09-15 01:30:00 1 + dtype: int64 + Be careful with DST changes. When there is sequential data, pandas can infer the DST time: From f978e67afbbf137589fff5e1ac8301d5f1d93ba4 Mon Sep 17 00:00:00 2001 From: Georeth Chow Date: Sat, 19 Nov 2022 02:22:14 +0800 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Matthew Roeschke <10647082+mroeschke@users.noreply.github.com> --- pandas/core/generic.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 1d2b06e0596e6..fa35060c8aff8 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -10140,7 +10140,7 @@ def tz_convert( Parameters ---------- tz : str or tzinfo object or None - Time zone to convert index to. Passing ``None`` will convert to + Target time zone. Passing ``None`` will convert to UTC and remove the timezone information. axis : the axis to convert level : int, str, default None @@ -10169,7 +10169,7 @@ def tz_convert( 2018-09-15 07:30:00+08:00 1 dtype: int64 - Convert to UTC and get a tz-naive index: + Pass None to convert to UTC and get a tz-naive index: >>> s = pd.Series([1], ... index=pd.DatetimeIndex(['2018-09-15 01:30:00+02:00'])) @@ -10227,7 +10227,7 @@ def tz_localize( Parameters ---------- tz : str or tzinfo or None - Time zone to convert the index to. pass ``None`` will remove the + Time zone to localize. Passing ``None`` will remove the time zone information and preserve local time. axis : the axis to localize level : int, str, default None @@ -10284,7 +10284,7 @@ def tz_localize( 2018-09-15 01:30:00+02:00 1 dtype: int64 - Convert to tz-naive index and preserve local time: + Pass None to convert to tz-naive index and preserve local time: >>> s = pd.Series([1], ... index=pd.DatetimeIndex(['2018-09-15 01:30:00+02:00']))