From f25ed6b9d3531a0a9d20308123b7b12839542c9c Mon Sep 17 00:00:00 2001 From: bartaelterman Date: Mon, 29 Oct 2018 11:26:25 +0100 Subject: [PATCH 01/10] Add documentation line with example for the ambiguous parameter of tz_locaclize --- pandas/core/generic.py | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 693cd14c8ca1d..f619887e769cc 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8623,6 +8623,13 @@ def tz_localize(self, tz, axis=0, level=None, copy=True, copy : boolean, default True Also make a copy of the underlying data ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise' + When clocks moved backward due to DST, ambiguous times may arise. + E.g. in Central European Time (UTC+01), when going from 03:00 DST + to 02:00 non-DST, the naive time 02:30:00 occurs both at + 00:30:00 UTC and at 01:30:00 UTC. In such a situation, the + `ambiguous` parameter can be used to correctly localize these + times. + - 'infer' will attempt to infer fall dst-transition hours based on order - bool-ndarray where True signifies a DST time, False designates From 551e149e85a994becf88d88f2527babac73e879c Mon Sep 17 00:00:00 2001 From: bartaelterman Date: Tue, 30 Oct 2018 09:30:48 +0100 Subject: [PATCH 02/10] Updating 'ambiguous'-param doc + update it on Timestamp, DatetimeIndex and NaT This is following the discussion at https://github.com/pandas-dev/pandas/pull/23408#discussion_r229109984 --- pandas/_libs/tslibs/conversion.pyx | 15 ++++++++++++++- pandas/_libs/tslibs/timestamps.pyx | 6 ++++++ pandas/core/generic.py | 9 ++++----- pandas/core/indexes/datetimes.py | 6 ++++++ 4 files changed, 30 insertions(+), 6 deletions(-) diff --git a/pandas/_libs/tslibs/conversion.pyx b/pandas/_libs/tslibs/conversion.pyx index f9c604cd76472..94907973a44d1 100644 --- a/pandas/_libs/tslibs/conversion.pyx +++ b/pandas/_libs/tslibs/conversion.pyx @@ -835,7 +835,20 @@ def tz_localize_to_utc(ndarray[int64_t] vals, object tz, object ambiguous=None, vals : ndarray[int64_t] tz : tzinfo or None ambiguous : str, bool, or arraylike - If arraylike, must have the same length as vals + When clocks moved backward due to DST, ambiguous times may arise. + For example in Central European Time (UTC+01), when going from 03:00 DST + to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC + and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter + dictates how ambiguous times should be handled. + + - 'infer' will attempt to infer fall dst-transition hours based on + order + - bool-ndarray where True signifies a DST time, False signifies a + non-DST time (note that this flag is only applicable for ambiguous + times, but the array must have the same length as vals) + - bool if True, treat all vals as DST. If False, treat them as non-DST + - 'NaT' will return NaT where there are ambiguous times + nonexistent : str If arraylike, must have the same length as vals diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index 08b0c5472549e..54689db070f02 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -974,6 +974,12 @@ class Timestamp(_Timestamp): None will remove timezone holding local time. ambiguous : bool, 'NaT', default 'raise' + When clocks moved backward due to DST, ambiguous times may arise. + For example in Central European Time (UTC+01), when going from 03:00 DST + to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC + and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter + dictates how ambiguous times should be handled. + - bool contains flags to determine if time is dst or not (note that this flag is only applicable for ambiguous fall dst dates) - 'NaT' will return NaT for an ambiguous time diff --git a/pandas/core/generic.py b/pandas/core/generic.py index f619887e769cc..51748391739b2 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8624,11 +8624,10 @@ def tz_localize(self, tz, axis=0, level=None, copy=True, Also make a copy of the underlying data ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise' When clocks moved backward due to DST, ambiguous times may arise. - E.g. in Central European Time (UTC+01), when going from 03:00 DST - to 02:00 non-DST, the naive time 02:30:00 occurs both at - 00:30:00 UTC and at 01:30:00 UTC. In such a situation, the - `ambiguous` parameter can be used to correctly localize these - times. + For example in Central European Time (UTC+01), when going from 03:00 DST + to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC + and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter + dictates how ambiguous times should be handled. - 'infer' will attempt to infer fall dst-transition hours based on order diff --git a/pandas/core/indexes/datetimes.py b/pandas/core/indexes/datetimes.py index 39f247a7c4cfe..8d62672b0b9cf 100644 --- a/pandas/core/indexes/datetimes.py +++ b/pandas/core/indexes/datetimes.py @@ -99,6 +99,12 @@ class DatetimeIndex(DatetimeArrayMixin, DatelikeOps, TimelikeOps, the 'left', 'right', or both sides (None) tz : pytz.timezone or dateutil.tz.tzfile ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise' + When clocks moved backward due to DST, ambiguous times may arise. + For example in Central European Time (UTC+01), when going from 03:00 DST + to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC + and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter + dictates how ambiguous times should be handled. + - 'infer' will attempt to infer fall dst-transition hours based on order - bool-ndarray where True signifies a DST time, False signifies a From 4274d08df82697ec86344b677ee91e04cf1bdaac Mon Sep 17 00:00:00 2001 From: bartaelterman Date: Tue, 30 Oct 2018 14:16:54 +0100 Subject: [PATCH 03/10] Add some examples for the ambiguous parameter for localizing timestamps --- pandas/core/generic.py | 44 ++++++++++++++++++++++++++++++++ pandas/core/indexes/datetimes.py | 39 ++++++++++++++++++++++++++++ 2 files changed, 83 insertions(+) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 51748391739b2..dab6453e93dfb 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8656,6 +8656,50 @@ def tz_localize(self, tz, axis=0, level=None, copy=True, ------ TypeError If the TimeSeries is tz-aware and tz is not None. + + Examples + -------- + + Localize local times: + + >>> s = pd.to_datetime(pd.Series(['2018-09-15 01:30:00'])) + >>> s.dt.tz_localize('CET') + 0 2018-09-15 01:30:00+02:00 + dtype: datetime64[ns, CET] + + Be careful with DST changes. When there is sequential data, pandas can infer the DST time: + + >>> s = pd.to_datetime(pd.Series([ + ... '2018-10-28 01:30:00', + ... '2018-10-28 02:00:00', + ... '2018-10-28 02:30:00', + ... '2018-10-28 02:00:00', + ... '2018-10-28 02:30:00', + ... '2018-10-28 03:00:00', + ... '2018-10-28 03:30:00'])) + >>> s.dt.tz_localize('CET', ambiguous='infer') + 1 2018-10-28 01:30:00+02:00 + 2 2018-10-28 02:00:00+02:00 + 3 2018-10-28 02:30:00+02:00 + 4 2018-10-28 02:00:00+01:00 + 5 2018-10-28 02:30:00+01:00 + 6 2018-10-28 03:00:00+01:00 + 7 2018-10-28 03:30:00+01:00 + dtype: datetime64[ns, CET] + + In some cases, inferring the DST is impossible. In such cases, you can + pass an ndarray to the ambiguous parameter to set the DST explicitly + + >>> s = pd.to_datetime(pd.Series([ + ... '2018-10-28 01:20:00', + ... '2018-10-28 02:36:00', + ... '2018-10-28 03:46:00'])) + >>> s.dt.tz_localize('CET', ambiguous=np.array([True, True, False])) + 0 2018-10-28 01:20:00+02:00 + 1 2018-10-28 02:36:00+02:00 + 2 2018-10-28 03:46:00+01:00 + dtype: datetime64[ns, CET] + """ if nonexistent not in ('raise', 'NaT', 'shift'): raise ValueError("The nonexistent argument must be one of 'raise'," diff --git a/pandas/core/indexes/datetimes.py b/pandas/core/indexes/datetimes.py index 8d62672b0b9cf..1a489e706d4b0 100644 --- a/pandas/core/indexes/datetimes.py +++ b/pandas/core/indexes/datetimes.py @@ -179,6 +179,45 @@ class DatetimeIndex(DatetimeArrayMixin, DatelikeOps, TimelikeOps, TimedeltaIndex : Index of timedelta64 data PeriodIndex : Index of Period data pandas.to_datetime : Convert argument to datetime + + Examples + -------- + + Localize local times: + + >>> s = pd.to_datetime(pd.Series(['2018-09-15 01:30:00'])) + >>> pd.DatetimeIndex(s, tz='CET') + DatetimeIndex(['2018-09-15 01:30:00+02:00'], dtype='datetime64[ns, CET]', freq=None) + + Be careful with DST changes. When there is sequential data, pandas can infer the DST time: + + >>> s = pd.to_datetime(pd.Series([ + ... '2018-10-28 01:30:00', + ... '2018-10-28 02:00:00', + ... '2018-10-28 02:30:00', + ... '2018-10-28 02:00:00', + ... '2018-10-28 02:30:00', + ... '2018-10-28 03:00:00', + ... '2018-10-28 03:30:00'])) + >>> pd.DatetimeIndex(s, tz='CET', ambiguous='infer') + DatetimeIndex(['2018-10-28 01:30:00+02:00', '2018-10-28 02:00:00+02:00', + '2018-10-28 02:30:00+02:00', '2018-10-28 02:00:00+01:00', + '2018-10-28 02:30:00+01:00', '2018-10-28 03:00:00+01:00', + '2018-10-28 03:30:00+01:00'], + dtype='datetime64[ns, CET]', freq=None) + + In some cases, inferring the DST is impossible. In such cases, you can + pass an ndarray to the ambiguous parameter to set the DST explicitly + + >>> s = pd.to_datetime(pd.Series([ + ... '2018-10-28 01:20:00', + ... '2018-10-28 02:36:00', + ... '2018-10-28 03:46:00'])) + >>> pd.DatetimeIndex(s, tz='CET', ambiguous=np.array([True, True, False])) + DatetimeIndex(['2018-10-28 01:20:00+02:00', '2018-10-28 02:36:00+02:00', + '2018-10-28 03:46:00+01:00'], + dtype='datetime64[ns, CET]', freq=None) + """ _resolution = cache_readonly(DatetimeArrayMixin._resolution.fget) From b33e3709c434d7f5b8e150f47dc269c3f75377dc Mon Sep 17 00:00:00 2001 From: bartaelterman Date: Wed, 31 Oct 2018 07:24:37 +0100 Subject: [PATCH 04/10] Make docstring of NaT tz_localize equal to Timestamp tz_localize --- pandas/_libs/tslibs/nattype.pyx | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index 0eec84ecf8285..618d9058c1b36 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -559,6 +559,12 @@ class NaTType(_NaT): None will remove timezone holding local time. ambiguous : bool, 'NaT', default 'raise' + When clocks moved backward due to DST, ambiguous times may arise. + For example in Central European Time (UTC+01), when going from 03:00 DST + to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC + and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter + dictates how ambiguous times should be handled. + - bool contains flags to determine if time is dst or not (note that this flag is only applicable for ambiguous fall dst dates) - 'NaT' will return NaT for an ambiguous time From a7b27b63930a74c9d7f80b04dff6e502f95d3eb0 Mon Sep 17 00:00:00 2001 From: bartaelterman Date: Wed, 31 Oct 2018 07:42:55 +0100 Subject: [PATCH 05/10] show example for Series.tz_localize (not dt.tz_localize) --- pandas/core/generic.py | 38 ++++++++++++++++---------------- pandas/core/indexes/datetimes.py | 38 -------------------------------- 2 files changed, 19 insertions(+), 57 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index dab6453e93dfb..9c6e6368c2c60 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8662,14 +8662,14 @@ def tz_localize(self, tz, axis=0, level=None, copy=True, Localize local times: - >>> s = pd.to_datetime(pd.Series(['2018-09-15 01:30:00'])) - >>> s.dt.tz_localize('CET') - 0 2018-09-15 01:30:00+02:00 - dtype: datetime64[ns, CET] + >>> s = pd.Series([1], index=pd.DatetimeIndex(['2018-09-15 01:30:00'])) + >>> s.tz_localize('CET') + 2018-09-15 01:30:00+02:00 1 + dtype: int64 Be careful with DST changes. When there is sequential data, pandas can infer the DST time: - >>> s = pd.to_datetime(pd.Series([ + >>> s = pd.Series(range(7), index=pd.DatetimeIndex([ ... '2018-10-28 01:30:00', ... '2018-10-28 02:00:00', ... '2018-10-28 02:30:00', @@ -8678,27 +8678,27 @@ def tz_localize(self, tz, axis=0, level=None, copy=True, ... '2018-10-28 03:00:00', ... '2018-10-28 03:30:00'])) >>> s.dt.tz_localize('CET', ambiguous='infer') - 1 2018-10-28 01:30:00+02:00 - 2 2018-10-28 02:00:00+02:00 - 3 2018-10-28 02:30:00+02:00 - 4 2018-10-28 02:00:00+01:00 - 5 2018-10-28 02:30:00+01:00 - 6 2018-10-28 03:00:00+01:00 - 7 2018-10-28 03:30:00+01:00 - dtype: datetime64[ns, CET] + 2018-10-28 01:30:00+02:00 0 + 2018-10-28 02:00:00+02:00 1 + 2018-10-28 02:30:00+02:00 2 + 2018-10-28 02:00:00+01:00 3 + 2018-10-28 02:30:00+01:00 4 + 2018-10-28 03:00:00+01:00 5 + 2018-10-28 03:30:00+01:00 6 + dtype: int64 In some cases, inferring the DST is impossible. In such cases, you can pass an ndarray to the ambiguous parameter to set the DST explicitly - >>> s = pd.to_datetime(pd.Series([ + >>> s = pd.Series(range(3), index=pd.DatetimeIndex([ ... '2018-10-28 01:20:00', ... '2018-10-28 02:36:00', ... '2018-10-28 03:46:00'])) - >>> s.dt.tz_localize('CET', ambiguous=np.array([True, True, False])) - 0 2018-10-28 01:20:00+02:00 - 1 2018-10-28 02:36:00+02:00 - 2 2018-10-28 03:46:00+01:00 - dtype: datetime64[ns, CET] + >>> s.tz_localize('CET', ambiguous=np.array([True, True, False])) + 2018-10-28 01:20:00+02:00 0 + 2018-10-28 02:36:00+02:00 1 + 2018-10-28 03:46:00+01:00 2 + dtype: int64 """ if nonexistent not in ('raise', 'NaT', 'shift'): diff --git a/pandas/core/indexes/datetimes.py b/pandas/core/indexes/datetimes.py index 1a489e706d4b0..befcc896bfe27 100644 --- a/pandas/core/indexes/datetimes.py +++ b/pandas/core/indexes/datetimes.py @@ -180,44 +180,6 @@ class DatetimeIndex(DatetimeArrayMixin, DatelikeOps, TimelikeOps, PeriodIndex : Index of Period data pandas.to_datetime : Convert argument to datetime - Examples - -------- - - Localize local times: - - >>> s = pd.to_datetime(pd.Series(['2018-09-15 01:30:00'])) - >>> pd.DatetimeIndex(s, tz='CET') - DatetimeIndex(['2018-09-15 01:30:00+02:00'], dtype='datetime64[ns, CET]', freq=None) - - Be careful with DST changes. When there is sequential data, pandas can infer the DST time: - - >>> s = pd.to_datetime(pd.Series([ - ... '2018-10-28 01:30:00', - ... '2018-10-28 02:00:00', - ... '2018-10-28 02:30:00', - ... '2018-10-28 02:00:00', - ... '2018-10-28 02:30:00', - ... '2018-10-28 03:00:00', - ... '2018-10-28 03:30:00'])) - >>> pd.DatetimeIndex(s, tz='CET', ambiguous='infer') - DatetimeIndex(['2018-10-28 01:30:00+02:00', '2018-10-28 02:00:00+02:00', - '2018-10-28 02:30:00+02:00', '2018-10-28 02:00:00+01:00', - '2018-10-28 02:30:00+01:00', '2018-10-28 03:00:00+01:00', - '2018-10-28 03:30:00+01:00'], - dtype='datetime64[ns, CET]', freq=None) - - In some cases, inferring the DST is impossible. In such cases, you can - pass an ndarray to the ambiguous parameter to set the DST explicitly - - >>> s = pd.to_datetime(pd.Series([ - ... '2018-10-28 01:20:00', - ... '2018-10-28 02:36:00', - ... '2018-10-28 03:46:00'])) - >>> pd.DatetimeIndex(s, tz='CET', ambiguous=np.array([True, True, False])) - DatetimeIndex(['2018-10-28 01:20:00+02:00', '2018-10-28 02:36:00+02:00', - '2018-10-28 03:46:00+01:00'], - dtype='datetime64[ns, CET]', freq=None) - """ _resolution = cache_readonly(DatetimeArrayMixin._resolution.fget) From efeeab7181a12951ada751677ffdaff2cc720642 Mon Sep 17 00:00:00 2001 From: bartaelterman Date: Wed, 31 Oct 2018 17:17:19 +0100 Subject: [PATCH 06/10] add ambiguous docstring to arrays/datetimes --- pandas/core/arrays/datetimes.py | 38 +++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/pandas/core/arrays/datetimes.py b/pandas/core/arrays/datetimes.py index b656690b30e34..1130a623cce6e 100644 --- a/pandas/core/arrays/datetimes.py +++ b/pandas/core/arrays/datetimes.py @@ -606,6 +606,11 @@ def tz_localize(self, tz, ambiguous='raise', nonexistent='raise', Time zone to convert timestamps to. Passing ``None`` will remove the time zone information preserving local time. ambiguous : 'infer', 'NaT', bool array, default 'raise' + When clocks moved backward due to DST, ambiguous times may arise. + For example in Central European Time (UTC+01), when going from 03:00 DST + to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC + and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter + dictates how ambiguous times should be handled. - 'infer' will attempt to infer fall dst-transition hours based on order @@ -677,6 +682,39 @@ def tz_localize(self, tz, ambiguous='raise', nonexistent='raise', DatetimeIndex(['2018-03-01 09:00:00', '2018-03-02 09:00:00', '2018-03-03 09:00:00'], dtype='datetime64[ns]', freq='D') + + Be careful with DST changes. When there is sequential data, pandas can infer the DST time: + >>> s = pd.to_datetime(pd.Series([ + ... '2018-10-28 01:30:00', + ... '2018-10-28 02:00:00', + ... '2018-10-28 02:30:00', + ... '2018-10-28 02:00:00', + ... '2018-10-28 02:30:00', + ... '2018-10-28 03:00:00', + ... '2018-10-28 03:30:00'])) + >>> s.dt.tz_localize('CET', ambiguous='infer') + 2018-10-28 01:30:00+02:00 0 + 2018-10-28 02:00:00+02:00 1 + 2018-10-28 02:30:00+02:00 2 + 2018-10-28 02:00:00+01:00 3 + 2018-10-28 02:30:00+01:00 4 + 2018-10-28 03:00:00+01:00 5 + 2018-10-28 03:30:00+01:00 6 + dtype: int64 + + In some cases, inferring the DST is impossible. In such cases, you can + pass an ndarray to the ambiguous parameter to set the DST explicitly + + >>> s = pd.to_datetime(pd.Series([ + ... '2018-10-28 01:20:00', + ... '2018-10-28 02:36:00', + ... '2018-10-28 03:46:00'])) + >>> s.dt.tz_localize('CET', ambiguous=np.array([True, True, False])) + 0 2018-10-28 01:20:00+02:00 + 1 2018-10-28 02:36:00+02:00 + 2 2018-10-28 03:46:00+01:00 + dtype: datetime64[ns, CET] + """ if errors is not None: warnings.warn("The errors argument is deprecated and will be " From 7e60b3d1565cac9aee1a00f5e832f1e18639ca71 Mon Sep 17 00:00:00 2001 From: bartaelterman Date: Wed, 31 Oct 2018 17:32:03 +0100 Subject: [PATCH 07/10] fix bug in the docstring --- pandas/core/generic.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 9c6e6368c2c60..e8ff2f1c6e494 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8677,7 +8677,7 @@ def tz_localize(self, tz, axis=0, level=None, copy=True, ... '2018-10-28 02:30:00', ... '2018-10-28 03:00:00', ... '2018-10-28 03:30:00'])) - >>> s.dt.tz_localize('CET', ambiguous='infer') + >>> s.tz_localize('CET', ambiguous='infer') 2018-10-28 01:30:00+02:00 0 2018-10-28 02:00:00+02:00 1 2018-10-28 02:30:00+02:00 2 From d18e80fb0a97312dd700e90bbc383175263d105f Mon Sep 17 00:00:00 2001 From: bartaelterman Date: Wed, 31 Oct 2018 21:24:53 +0100 Subject: [PATCH 08/10] chop off long lines in docstring --- pandas/_libs/tslibs/conversion.pyx | 4 ++-- pandas/_libs/tslibs/nattype.pyx | 4 ++-- pandas/_libs/tslibs/timestamps.pyx | 4 ++-- pandas/core/arrays/datetimes.py | 12 +++++++----- pandas/core/generic.py | 9 +++++---- pandas/core/indexes/datetimes.py | 4 ++-- 6 files changed, 20 insertions(+), 17 deletions(-) diff --git a/pandas/_libs/tslibs/conversion.pyx b/pandas/_libs/tslibs/conversion.pyx index 94907973a44d1..7263fde5eb530 100644 --- a/pandas/_libs/tslibs/conversion.pyx +++ b/pandas/_libs/tslibs/conversion.pyx @@ -836,8 +836,8 @@ def tz_localize_to_utc(ndarray[int64_t] vals, object tz, object ambiguous=None, tz : tzinfo or None ambiguous : str, bool, or arraylike When clocks moved backward due to DST, ambiguous times may arise. - For example in Central European Time (UTC+01), when going from 03:00 DST - to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC + For example in Central European Time (UTC+01), when going from 03:00 + DST to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter dictates how ambiguous times should be handled. diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index 618d9058c1b36..b6f25d8cf3e95 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -560,8 +560,8 @@ class NaTType(_NaT): ambiguous : bool, 'NaT', default 'raise' When clocks moved backward due to DST, ambiguous times may arise. - For example in Central European Time (UTC+01), when going from 03:00 DST - to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC + For example in Central European Time (UTC+01), when going from 03:00 + DST to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter dictates how ambiguous times should be handled. diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index 54689db070f02..411e7078b76c4 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -975,8 +975,8 @@ class Timestamp(_Timestamp): ambiguous : bool, 'NaT', default 'raise' When clocks moved backward due to DST, ambiguous times may arise. - For example in Central European Time (UTC+01), when going from 03:00 DST - to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC + For example in Central European Time (UTC+01), when going from 03:00 + DST to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter dictates how ambiguous times should be handled. diff --git a/pandas/core/arrays/datetimes.py b/pandas/core/arrays/datetimes.py index 1130a623cce6e..fd3e5cedcfe77 100644 --- a/pandas/core/arrays/datetimes.py +++ b/pandas/core/arrays/datetimes.py @@ -607,10 +607,11 @@ def tz_localize(self, tz, ambiguous='raise', nonexistent='raise', remove the time zone information preserving local time. ambiguous : 'infer', 'NaT', bool array, default 'raise' When clocks moved backward due to DST, ambiguous times may arise. - For example in Central European Time (UTC+01), when going from 03:00 DST - to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC - and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter - dictates how ambiguous times should be handled. + For example in Central European Time (UTC+01), when going from + 03:00 DST to 02:00 non-DST, 02:30:00 local time occurs both at + 00:30:00 UTC and at 01:30:00 UTC. In such a situation, the + `ambiguous` parameter dictates how ambiguous times should be + handled. - 'infer' will attempt to infer fall dst-transition hours based on order @@ -683,7 +684,8 @@ def tz_localize(self, tz, ambiguous='raise', nonexistent='raise', '2018-03-03 09:00:00'], dtype='datetime64[ns]', freq='D') - Be careful with DST changes. When there is sequential data, pandas can infer the DST time: + Be careful with DST changes. When there is sequential data, pandas can + infer the DST time: >>> s = pd.to_datetime(pd.Series([ ... '2018-10-28 01:30:00', ... '2018-10-28 02:00:00', diff --git a/pandas/core/generic.py b/pandas/core/generic.py index e8ff2f1c6e494..9b8d4a4d4e87c 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8624,10 +8624,11 @@ def tz_localize(self, tz, axis=0, level=None, copy=True, Also make a copy of the underlying data ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise' When clocks moved backward due to DST, ambiguous times may arise. - For example in Central European Time (UTC+01), when going from 03:00 DST - to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC - and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter - dictates how ambiguous times should be handled. + For example in Central European Time (UTC+01), when going from + 03:00 DST to 02:00 non-DST, 02:30:00 local time occurs both at + 00:30:00 UTC and at 01:30:00 UTC. In such a situation, the + `ambiguous` parameter dictates how ambiguous times should be + handled. - 'infer' will attempt to infer fall dst-transition hours based on order diff --git a/pandas/core/indexes/datetimes.py b/pandas/core/indexes/datetimes.py index befcc896bfe27..d3cd4d834dfa0 100644 --- a/pandas/core/indexes/datetimes.py +++ b/pandas/core/indexes/datetimes.py @@ -100,8 +100,8 @@ class DatetimeIndex(DatetimeArrayMixin, DatelikeOps, TimelikeOps, tz : pytz.timezone or dateutil.tz.tzfile ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise' When clocks moved backward due to DST, ambiguous times may arise. - For example in Central European Time (UTC+01), when going from 03:00 DST - to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC + For example in Central European Time (UTC+01), when going from 03:00 + DST to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter dictates how ambiguous times should be handled. From 4a9ad4bffb0a2dc8513628ca045c5514d7f97d8a Mon Sep 17 00:00:00 2001 From: bartaelterman Date: Wed, 31 Oct 2018 22:21:40 +0100 Subject: [PATCH 09/10] chop long lines in docstring --- pandas/_libs/tslibs/nattype.pyx | 9 +++++---- pandas/_libs/tslibs/timestamps.pyx | 9 +++++---- 2 files changed, 10 insertions(+), 8 deletions(-) diff --git a/pandas/_libs/tslibs/nattype.pyx b/pandas/_libs/tslibs/nattype.pyx index b6f25d8cf3e95..be35ae1172f7e 100644 --- a/pandas/_libs/tslibs/nattype.pyx +++ b/pandas/_libs/tslibs/nattype.pyx @@ -560,10 +560,11 @@ class NaTType(_NaT): ambiguous : bool, 'NaT', default 'raise' When clocks moved backward due to DST, ambiguous times may arise. - For example in Central European Time (UTC+01), when going from 03:00 - DST to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC - and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter - dictates how ambiguous times should be handled. + For example in Central European Time (UTC+01), when going from + 03:00 DST to 02:00 non-DST, 02:30:00 local time occurs both at + 00:30:00 UTC and at 01:30:00 UTC. In such a situation, the + `ambiguous` parameter dictates how ambiguous times should be + handled. - bool contains flags to determine if time is dst or not (note that this flag is only applicable for ambiguous fall dst dates) diff --git a/pandas/_libs/tslibs/timestamps.pyx b/pandas/_libs/tslibs/timestamps.pyx index 411e7078b76c4..89092af68b168 100644 --- a/pandas/_libs/tslibs/timestamps.pyx +++ b/pandas/_libs/tslibs/timestamps.pyx @@ -975,10 +975,11 @@ class Timestamp(_Timestamp): ambiguous : bool, 'NaT', default 'raise' When clocks moved backward due to DST, ambiguous times may arise. - For example in Central European Time (UTC+01), when going from 03:00 - DST to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC - and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter - dictates how ambiguous times should be handled. + For example in Central European Time (UTC+01), when going from + 03:00 DST to 02:00 non-DST, 02:30:00 local time occurs both at + 00:30:00 UTC and at 01:30:00 UTC. In such a situation, the + `ambiguous` parameter dictates how ambiguous times should be + handled. - bool contains flags to determine if time is dst or not (note that this flag is only applicable for ambiguous fall dst dates) From b1026c389b32e95d9e439b3b2fa0e16252908588 Mon Sep 17 00:00:00 2001 From: bartaelterman Date: Thu, 1 Nov 2018 00:03:45 +0100 Subject: [PATCH 10/10] chop long line in docstring --- pandas/core/generic.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/pandas/core/generic.py b/pandas/core/generic.py index 9b8d4a4d4e87c..96bdb7cc2146a 100644 --- a/pandas/core/generic.py +++ b/pandas/core/generic.py @@ -8663,12 +8663,14 @@ def tz_localize(self, tz, axis=0, level=None, copy=True, Localize local times: - >>> s = pd.Series([1], index=pd.DatetimeIndex(['2018-09-15 01:30:00'])) + >>> s = pd.Series([1], + ... index=pd.DatetimeIndex(['2018-09-15 01:30:00'])) >>> s.tz_localize('CET') 2018-09-15 01:30:00+02:00 1 dtype: int64 - Be careful with DST changes. When there is sequential data, pandas can infer the DST time: + Be careful with DST changes. When there is sequential data, pandas + can infer the DST time: >>> s = pd.Series(range(7), index=pd.DatetimeIndex([ ... '2018-10-28 01:30:00',