From 2d3f8819af0dfb56e3df8f778fe25145fba698ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Wed, 21 Jun 2023 12:03:23 +0200 Subject: [PATCH 1/5] examples TimedeltaArray, Period.asfreq --- pandas/_libs/tslibs/period.pyx | 6 ++++++ pandas/core/arrays/timedeltas.py | 7 +++++++ 2 files changed, 13 insertions(+) diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index e954ec9bccd9e..31c3d0e815123 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -1924,6 +1924,12 @@ cdef class _Period(PeriodMixin): Returns ------- resampled : Period + + Examples + -------- + >>> period = pd.Period('2023-1-1', freq='D') + >>> period.asfreq('H') + Period('2023-01-01 23:00', 'H') """ freq = self._maybe_convert_freq(freq) how = validate_end_alias(how) diff --git a/pandas/core/arrays/timedeltas.py b/pandas/core/arrays/timedeltas.py index bf62c327de2f0..6b0ed2bf79238 100644 --- a/pandas/core/arrays/timedeltas.py +++ b/pandas/core/arrays/timedeltas.py @@ -132,6 +132,13 @@ class TimedeltaArray(dtl.TimelikeOps): Methods ------- None + + Examples + -------- + >>> pd.arrays.DatetimeArray(pd.TimedeltaIndex(['1H', '2H'])) + + ['0 days 01:00:00', '0 days 02:00:00'] + Length: 2, dtype: timedelta64[ns] """ _typ = "timedeltaarray" From e4dd4df5e4b1af0a283fff4c7e84fe9223a3d28c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Thu, 22 Jun 2023 14:31:54 +0200 Subject: [PATCH 2/5] Examples for categoricals --- pandas/_libs/tslibs/period.pyx | 5 +++++ pandas/core/arrays/categorical.py | 32 +++++++++++++++++++++++++++++++ pandas/core/arrays/period.py | 8 ++++++++ pandas/core/dtypes/dtypes.py | 16 ++++++++++++++++ 4 files changed, 61 insertions(+) diff --git a/pandas/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 31c3d0e815123..b23d0f3688236 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -2465,6 +2465,11 @@ cdef class _Period(PeriodMixin): ---------- freq : str, BaseOffset Frequency to use for the returned period. + + Examples + -------- + >>> pd.Period.now('H') # doctest: +SKIP + Period('2023-06-12 11:00', 'H') """ return Period(datetime.now(), freq=freq) diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index 97ed64856fe3b..acd8223e8b900 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -481,6 +481,16 @@ def __init__( def dtype(self) -> CategoricalDtype: """ The :class:`~pandas.api.types.CategoricalDtype` for this instance. + + Examples + -------- + >>> cat = pd.Categorical(['a', 'b'], ordered=True) + >>> cat + ['a', 'b'] + Categories (2, object): ['a' < 'b'] + >>> cat.dtype + CategoricalDtype(categories=['a', 'b'], ordered=True, + categories_dtype=object) """ return self._dtype @@ -751,6 +761,9 @@ def categories(self) -> Index: Examples -------- + + For Series: + >>> ser = pd.Series(["a", "b", "c", "a"], dtype="category") >>> ser.cat.categories Index(['a', 'b', 'c'], dtype='object') @@ -759,6 +772,12 @@ def categories(self) -> Index: >>> ser = pd.Series(raw_cat) >>> ser.cat.categories Index(['b', 'c', 'd'], dtype='object') + + For Categories: + + >>> cat = pd.Categorical(['a', 'b'], ordered=True) + >>> cat.categories + Index(['a', 'b'], dtype='object') """ return self.dtype.categories @@ -769,6 +788,9 @@ def ordered(self) -> Ordered: Examples -------- + + For Series: + >>> ser = pd.Series(["a", "b", "c", "a"], dtype="category") >>> ser.cat.ordered False @@ -777,6 +799,16 @@ def ordered(self) -> Ordered: >>> ser = pd.Series(raw_cat) >>> ser.cat.ordered True + + For Categories: + + >>> cat = pd.Categorical(['a', 'b'], ordered=True) + >>> cat.ordered + True + + >>> cat = pd.Categorical(['a', 'b'], ordered=False) + >>> cat.ordered + False """ return self.dtype.ordered diff --git a/pandas/core/arrays/period.py b/pandas/core/arrays/period.py index 266dda52c6d0d..c9c2d258a9a16 100644 --- a/pandas/core/arrays/period.py +++ b/pandas/core/arrays/period.py @@ -163,6 +163,14 @@ class PeriodArray(dtl.DatelikeOps, libperiod.PeriodMixin): # type: ignore[misc] The `freq` indicates the span covered by each element of the array. All elements in the PeriodArray have the same `freq`. + + Examples + -------- + >>> pd.arrays.PeriodArray(pd.PeriodIndex(['2023-01-01', + ... '2023-01-02'], freq='D')) + + ['2023-01-01', '2023-01-02'] + Length: 2, dtype: period[D] """ # array priority higher than numpy scalars diff --git a/pandas/core/dtypes/dtypes.py b/pandas/core/dtypes/dtypes.py index 820364fa3f61a..03e94aa6d3d7c 100644 --- a/pandas/core/dtypes/dtypes.py +++ b/pandas/core/dtypes/dtypes.py @@ -610,6 +610,12 @@ def update_dtype(self, dtype: str_type | CategoricalDtype) -> CategoricalDtype: def categories(self) -> Index: """ An ``Index`` containing the unique categories allowed. + + Examples + -------- + >>> cat_type = pd.CategoricalDtype(categories=['a', 'b'], ordered=True) + >>> cat_type.categories + Index(['a', 'b'], dtype='object') """ return self._categories @@ -617,6 +623,16 @@ def categories(self) -> Index: def ordered(self) -> Ordered: """ Whether the categories have an ordered relationship. + + Examples + -------- + >>> cat_type = pd.CategoricalDtype(categories=['a', 'b'], ordered=True) + >>> cat_type.ordered + True + + >>> cat_type = pd.CategoricalDtype(categories=['a', 'b'], ordered=False) + >>> cat_type.ordered + False """ return self._ordered From ac0a9437cec96307f39c2ea3af4e6ee994ddcf3a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Thu, 22 Jun 2023 17:00:18 +0200 Subject: [PATCH 3/5] Exampl Categorical.codes and .__array__, edited code_checks --- ci/code_checks.sh | 11 ----------- pandas/core/arrays/categorical.py | 16 ++++++++++++++++ 2 files changed, 16 insertions(+), 11 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 693017c6715ae..472bd78e4d3bc 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -105,17 +105,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.errors.UnsupportedFunctionCall \ pandas.test \ pandas.NaT \ - pandas.arrays.TimedeltaArray \ - pandas.Period.asfreq \ - pandas.Period.now \ - pandas.arrays.PeriodArray \ - pandas.CategoricalDtype.categories \ - pandas.CategoricalDtype.ordered \ - pandas.Categorical.dtype \ - pandas.Categorical.categories \ - pandas.Categorical.ordered \ - pandas.Categorical.codes \ - pandas.Categorical.__array__ \ pandas.SparseDtype \ pandas.DatetimeTZDtype.unit \ pandas.DatetimeTZDtype.tz \ diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index acd8223e8b900..b5cc979bf2650 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -827,6 +827,12 @@ def codes(self) -> np.ndarray: ------- ndarray[int] A non-writable view of the `codes` array. + + Examples + -------- + >>> cat = pd.Categorical(['a', 'b'], ordered=True) + >>> cat.codes + array([0, 1], dtype=int8) """ v = self._codes.view() v.flags.writeable = False @@ -1524,6 +1530,16 @@ def __array__(self, dtype: NpDtype | None = None) -> np.ndarray: A numpy array of either the specified dtype or, if dtype==None (default), the same dtype as categorical.categories.dtype. + + Examples + -------- + + >>> cat = pd.Categorical(['a', 'b'], ordered=True) + + The following calls cat.__array__ + + >>> np.asarray(cat) + array(['a', 'b'], dtype=object) """ ret = take_nd(self.categories._values, self._codes) if dtype and np.dtype(dtype) != self.categories.dtype: From 6e054a3b972b937652a4377f6e5079ccb9058f1f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Fri, 23 Jun 2023 10:49:31 +0200 Subject: [PATCH 4/5] Corrected TimedeltaArray and wording to categorical --- pandas/core/arrays/categorical.py | 6 +++--- pandas/core/arrays/timedeltas.py | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index b5cc979bf2650..6db92047f2978 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -773,7 +773,7 @@ def categories(self) -> Index: >>> ser.cat.categories Index(['b', 'c', 'd'], dtype='object') - For Categories: + For Categorical: >>> cat = pd.Categorical(['a', 'b'], ordered=True) >>> cat.categories @@ -800,7 +800,7 @@ def ordered(self) -> Ordered: >>> ser.cat.ordered True - For Categories: + For Categorical: >>> cat = pd.Categorical(['a', 'b'], ordered=True) >>> cat.ordered @@ -1536,7 +1536,7 @@ def __array__(self, dtype: NpDtype | None = None) -> np.ndarray: >>> cat = pd.Categorical(['a', 'b'], ordered=True) - The following calls cat.__array__ + The following calls ``cat.__array__`` >>> np.asarray(cat) array(['a', 'b'], dtype=object) diff --git a/pandas/core/arrays/timedeltas.py b/pandas/core/arrays/timedeltas.py index 6b0ed2bf79238..2516e687cdbab 100644 --- a/pandas/core/arrays/timedeltas.py +++ b/pandas/core/arrays/timedeltas.py @@ -135,7 +135,7 @@ class TimedeltaArray(dtl.TimelikeOps): Examples -------- - >>> pd.arrays.DatetimeArray(pd.TimedeltaIndex(['1H', '2H'])) + >>> pd.arrays.TimedeltaArray(pd.TimedeltaIndex(['1H', '2H'])) ['0 days 01:00:00', '0 days 02:00:00'] Length: 2, dtype: timedelta64[ns] From d297e7dd96b362514bd68f7c48eb8fb8e3f6229a Mon Sep 17 00:00:00 2001 From: MarcoGorelli <33491632+MarcoGorelli@users.noreply.github.com> Date: Fri, 23 Jun 2023 15:31:03 +0100 Subject: [PATCH 5/5] remove multiline --- pandas/core/arrays/categorical.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/pandas/core/arrays/categorical.py b/pandas/core/arrays/categorical.py index 6db92047f2978..a226c71934a64 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -489,8 +489,7 @@ def dtype(self) -> CategoricalDtype: ['a', 'b'] Categories (2, object): ['a' < 'b'] >>> cat.dtype - CategoricalDtype(categories=['a', 'b'], ordered=True, - categories_dtype=object) + CategoricalDtype(categories=['a', 'b'], ordered=True, categories_dtype=object) """ return self._dtype