From 6a7efbc0c246d09461b809857b53e12fa9ceb9f5 Mon Sep 17 00:00:00 2001 From: Dea Leon Date: Thu, 16 Feb 2023 21:05:33 +0100 Subject: [PATCH 1/2] DOC Fix EX01 issues in docstrings --- ci/code_checks.sh | 3 --- pandas/_libs/tslibs/period.pyx | 7 +++++++ pandas/core/frame.py | 20 ++++++++++++++++++++ pandas/core/series.py | 29 +++++++++++++++++++++++++++++ 4 files changed, 56 insertions(+), 3 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index d342a588bc897..2be3a56fb236b 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -91,7 +91,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.Series.size \ pandas.Series.T \ pandas.Series.hasnans \ - pandas.Series.to_timestamp \ pandas.Series.to_list \ pandas.Series.__iter__ \ pandas.Series.keys \ @@ -218,7 +217,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.Period.year \ pandas.Period.asfreq \ pandas.Period.now \ - pandas.Period.to_timestamp \ pandas.arrays.PeriodArray \ pandas.Interval.closed \ pandas.Interval.left \ @@ -562,7 +560,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.DataFrame.swapaxes \ pandas.DataFrame.first_valid_index \ pandas.DataFrame.last_valid_index \ - pandas.DataFrame.to_timestamp \ pandas.DataFrame.attrs \ pandas.DataFrame.plot \ pandas.DataFrame.sparse.density \ diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 77c8be6be07e4..f35c185b325cf 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -1841,6 +1841,13 @@ cdef class _Period(PeriodMixin): Returns ------- Timestamp + + Examples + -------- + >>> period = pd.Period('2023-1-1', freq='D') + >>> period = period.to_timestamp() + >>> period + Timestamp('2023-01-01 00:00:00') """ how = validate_end_alias(how) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 79f423b17383d..726dae7cca4b3 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -11013,6 +11013,26 @@ def to_timestamp( ------- DataFrame The DataFrame has a DatetimeIndex. + + Examples + -------- + >>> idx = pd.PeriodIndex(['2023', '2024'], freq='Y') + >>> d = {'col1': [1, 2], 'col2': [3, 4]} + >>> df = pd.DataFrame(data=d, index=idx) + >>> df + col1 col2 + 2023 1 3 + 2024 2 4 + + The resulting timestamps will be at the beginning of the year in this case + + >>> df = df.to_timestamp() + >>> df + col1 col2 + 2023-01-01 1 3 + 2024-01-01 2 4 + >>> df.index + DatetimeIndex(['2023-01-01', '2024-01-01'], dtype='datetime64[ns]', freq=None) """ new_obj = self.copy(deep=copy) diff --git a/pandas/core/series.py b/pandas/core/series.py index d69c057c85783..9693cac38a01c 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -5710,6 +5710,35 @@ def to_timestamp( Returns ------- Series with DatetimeIndex + + Examples + -------- + >>> idx = pd.PeriodIndex(['2023', '2024', '2025'], freq='Y') + >>> s1 = pd.Series([1, 2, 3], index=idx) + >>> s1 + 2023 1 + 2024 2 + 2025 3 + Freq: A-DEC, dtype: int64 + + The resulting frequency of the Timestamps is `YearBegin` + + >>> s1 = s1.to_timestamp() + >>> s1 + 2023-01-01 1 + 2024-01-01 2 + 2025-01-01 3 + Freq: AS-JAN, dtype: int64 + + Using `freq` which is the offset that the Timestamps will have + + >>> s2 = pd.Series([1, 2, 3], index=idx) + >>> s2 = s2.to_timestamp(freq='M') + >>> s2 + 2023-01-31 1 + 2024-01-31 2 + 2025-01-31 3 + Freq: A-JAN, dtype: int64 """ if not isinstance(self.index, PeriodIndex): raise TypeError(f"unsupported Type {type(self.index).__name__}") From da9a672367a47e7672847576ca52a6c6cf397725 Mon Sep 17 00:00:00 2001 From: Dea Leon Date: Fri, 17 Feb 2023 15:30:11 +0100 Subject: [PATCH 2/2] DOC Fix EX01- correct var name+added to example --- pandas/_libs/tslibs/period.pyx | 4 ++-- pandas/core/frame.py | 21 ++++++++++++++++----- 2 files changed, 18 insertions(+), 7 deletions(-) diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index f35c185b325cf..f44178700503d 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -1845,8 +1845,8 @@ cdef class _Period(PeriodMixin): Examples -------- >>> period = pd.Period('2023-1-1', freq='D') - >>> period = period.to_timestamp() - >>> period + >>> timestamp = period.to_timestamp() + >>> timestamp Timestamp('2023-01-01 00:00:00') """ how = validate_end_alias(how) diff --git a/pandas/core/frame.py b/pandas/core/frame.py index 726dae7cca4b3..16fc4a19aefaf 100644 --- a/pandas/core/frame.py +++ b/pandas/core/frame.py @@ -11018,21 +11018,32 @@ def to_timestamp( -------- >>> idx = pd.PeriodIndex(['2023', '2024'], freq='Y') >>> d = {'col1': [1, 2], 'col2': [3, 4]} - >>> df = pd.DataFrame(data=d, index=idx) - >>> df + >>> df1 = pd.DataFrame(data=d, index=idx) + >>> df1 col1 col2 2023 1 3 2024 2 4 The resulting timestamps will be at the beginning of the year in this case - >>> df = df.to_timestamp() - >>> df + >>> df1 = df1.to_timestamp() + >>> df1 col1 col2 2023-01-01 1 3 2024-01-01 2 4 - >>> df.index + >>> df1.index DatetimeIndex(['2023-01-01', '2024-01-01'], dtype='datetime64[ns]', freq=None) + + Using `freq` which is the offset that the Timestamps will have + + >>> df2 = pd.DataFrame(data=d, index=idx) + >>> df2 = df2.to_timestamp(freq='M') + >>> df2 + col1 col2 + 2023-01-31 1 3 + 2024-01-31 2 4 + >>> df2.index + DatetimeIndex(['2023-01-31', '2024-01-31'], dtype='datetime64[ns]', freq=None) """ new_obj = self.copy(deep=copy)