From 26d1f5d34c123d219a501a1ce8166fa218a219bb Mon Sep 17 00:00:00 2001 From: Cihan Ceyhan Date: Sat, 10 Mar 2018 16:19:50 +0100 Subject: [PATCH 1/3] DOC: Update the pandas.Series.dt.round/floor/ceil docstrings --- pandas/core/indexes/datetimelike.py | 50 +++++++++++++++++++++++++---- 1 file changed, 44 insertions(+), 6 deletions(-) diff --git a/pandas/core/indexes/datetimelike.py b/pandas/core/indexes/datetimelike.py index e673bfe411cb4..e9e7d5fad0189 100644 --- a/pandas/core/indexes/datetimelike.py +++ b/pandas/core/indexes/datetimelike.py @@ -82,21 +82,59 @@ class TimelikeOps(object): _round_doc = ( """ - %s the index to the specified freq + {op} the index to the specified `freq`. Parameters ---------- freq : freq string/object + The frequency level to {op} the index to. Returns ------- - index of same type + index of same type. Raises ------ - ValueError if the freq cannot be converted + ValueError if the `freq` cannot be converted. + + Notes + ----- + See the following link for possible `freq` values + and their descriptions.\n + https://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases + + Examples + -------- + >>> rng = pd.date_range('1/1/2018 11:59:00', periods=3, freq='min') + >>> rng + DatetimeIndex(['2018-01-01 11:59:00', '2018-01-01 12:00:00', + '2018-01-01 12:01:00'], + dtype='datetime64[ns]', freq='T') + """) + + _round_example = ( + """>>> rng.round('H') + DatetimeIndex(['2018-01-01 12:00:00', '2018-01-01 12:00:00', + '2018-01-01 12:00:00'], + dtype='datetime64[ns]', freq=None) """) + _floor_example = ( + """>>> rng.floor('H') + DatetimeIndex(['2018-01-01 11:00:00', '2018-01-01 12:00:00', + '2018-01-01 12:00:00'], + dtype='datetime64[ns]', freq=None) + """ + ) + + _ceil_example = ( + """>>> rng.ceil('H') + DatetimeIndex(['2018-01-01 12:00:00', '2018-01-01 12:00:00', + '2018-01-01 13:00:00'], + dtype='datetime64[ns]', freq=None) + """ + ) + def _round(self, freq, rounder): # round the local times values = _ensure_datetimelike_to_i8(self) @@ -111,15 +149,15 @@ def _round(self, freq, rounder): return self._ensure_localized( self._shallow_copy(result, **attribs)) - @Appender(_round_doc % "round") + @Appender((_round_doc + _round_example).format(op="round")) def round(self, freq, *args, **kwargs): return self._round(freq, np.round) - @Appender(_round_doc % "floor") + @Appender((_round_doc + _floor_example).format(op="floor")) def floor(self, freq): return self._round(freq, np.floor) - @Appender(_round_doc % "ceil") + @Appender((_round_doc + _ceil_example).format(op="ceil")) def ceil(self, freq): return self._round(freq, np.ceil) From e58f4069ef1ec49d3e6587cffd429ff1c39ba35d Mon Sep 17 00:00:00 2001 From: Cihan Ceyhan Date: Sat, 10 Mar 2018 19:53:33 +0100 Subject: [PATCH 2/3] DOC: review points fixed. --- pandas/core/indexes/datetimelike.py | 21 ++++++++++----------- 1 file changed, 10 insertions(+), 11 deletions(-) diff --git a/pandas/core/indexes/datetimelike.py b/pandas/core/indexes/datetimelike.py index e9e7d5fad0189..699a4524f1ea6 100644 --- a/pandas/core/indexes/datetimelike.py +++ b/pandas/core/indexes/datetimelike.py @@ -99,39 +99,38 @@ class TimelikeOps(object): Notes ----- - See the following link for possible `freq` values - and their descriptions.\n - https://pandas.pydata.org/pandas-docs/stable/timeseries.html#offset-aliases + See :ref:`frequency aliases ` for + a list of possible `freq` values. Examples -------- >>> rng = pd.date_range('1/1/2018 11:59:00', periods=3, freq='min') >>> rng DatetimeIndex(['2018-01-01 11:59:00', '2018-01-01 12:00:00', - '2018-01-01 12:01:00'], - dtype='datetime64[ns]', freq='T') + '2018-01-01 12:01:00'], + dtype='datetime64[ns]', freq='T') """) _round_example = ( """>>> rng.round('H') DatetimeIndex(['2018-01-01 12:00:00', '2018-01-01 12:00:00', - '2018-01-01 12:00:00'], - dtype='datetime64[ns]', freq=None) + '2018-01-01 12:00:00'], + dtype='datetime64[ns]', freq=None) """) _floor_example = ( """>>> rng.floor('H') DatetimeIndex(['2018-01-01 11:00:00', '2018-01-01 12:00:00', - '2018-01-01 12:00:00'], - dtype='datetime64[ns]', freq=None) + '2018-01-01 12:00:00'], + dtype='datetime64[ns]', freq=None) """ ) _ceil_example = ( """>>> rng.ceil('H') DatetimeIndex(['2018-01-01 12:00:00', '2018-01-01 12:00:00', - '2018-01-01 13:00:00'], - dtype='datetime64[ns]', freq=None) + '2018-01-01 13:00:00'], + dtype='datetime64[ns]', freq=None) """ ) From fcd3bdfaea0aa6368ca799719b036623e46e739a Mon Sep 17 00:00:00 2001 From: Tom Augspurger Date: Sun, 11 Mar 2018 15:47:05 -0500 Subject: [PATCH 3/3] Add series --- pandas/core/indexes/datetimelike.py | 52 +++++++++++++++++++++-------- 1 file changed, 39 insertions(+), 13 deletions(-) diff --git a/pandas/core/indexes/datetimelike.py b/pandas/core/indexes/datetimelike.py index 699a4524f1ea6..1c41488973978 100644 --- a/pandas/core/indexes/datetimelike.py +++ b/pandas/core/indexes/datetimelike.py @@ -82,47 +82,65 @@ class TimelikeOps(object): _round_doc = ( """ - {op} the index to the specified `freq`. + {op} the data to the specified `freq`. Parameters ---------- - freq : freq string/object - The frequency level to {op} the index to. + freq : str or Offset + The frequency level to {op} the index to. Must be a fixed + frequency like 'S' (second) not 'ME' (month end). See + :ref:`frequency aliases ` for + a list of possible `freq` values. Returns ------- - index of same type. + DatetimeIndex, TimedeltaIndex, or Series + Index of the same type for a DatetimeIndex or TimedeltaIndex, + or a Series with the same index for a Series. Raises ------ ValueError if the `freq` cannot be converted. - Notes - ----- - See :ref:`frequency aliases ` for - a list of possible `freq` values. - Examples -------- + **DatetimeIndex** + >>> rng = pd.date_range('1/1/2018 11:59:00', periods=3, freq='min') >>> rng DatetimeIndex(['2018-01-01 11:59:00', '2018-01-01 12:00:00', '2018-01-01 12:01:00'], - dtype='datetime64[ns]', freq='T') + dtype='datetime64[ns]', freq='T') """) _round_example = ( """>>> rng.round('H') DatetimeIndex(['2018-01-01 12:00:00', '2018-01-01 12:00:00', '2018-01-01 12:00:00'], - dtype='datetime64[ns]', freq=None) + dtype='datetime64[ns]', freq=None) + + **Series** + + >>> pd.Series(rng).dt.round("H") + 0 2018-01-01 12:00:00 + 1 2018-01-01 12:00:00 + 2 2018-01-01 12:00:00 + dtype: datetime64[ns] """) _floor_example = ( """>>> rng.floor('H') DatetimeIndex(['2018-01-01 11:00:00', '2018-01-01 12:00:00', '2018-01-01 12:00:00'], - dtype='datetime64[ns]', freq=None) + dtype='datetime64[ns]', freq=None) + + **Series** + + >>> pd.Series(rng).dt.floor("H") + 0 2018-01-01 11:00:00 + 1 2018-01-01 12:00:00 + 2 2018-01-01 12:00:00 + dtype: datetime64[ns] """ ) @@ -130,7 +148,15 @@ class TimelikeOps(object): """>>> rng.ceil('H') DatetimeIndex(['2018-01-01 12:00:00', '2018-01-01 12:00:00', '2018-01-01 13:00:00'], - dtype='datetime64[ns]', freq=None) + dtype='datetime64[ns]', freq=None) + + **Series** + + >>> pd.Series(rng).dt.ceil("H") + 0 2018-01-01 12:00:00 + 1 2018-01-01 12:00:00 + 2 2018-01-01 13:00:00 + dtype: datetime64[ns] """ )