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/_libs/tslibs/period.pyx b/pandas/_libs/tslibs/period.pyx index 2ec0649110948..0a181c5bfdfa0 100644 --- a/pandas/_libs/tslibs/period.pyx +++ b/pandas/_libs/tslibs/period.pyx @@ -1925,6 +1925,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) @@ -2460,6 +2466,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..a226c71934a64 100644 --- a/pandas/core/arrays/categorical.py +++ b/pandas/core/arrays/categorical.py @@ -481,6 +481,15 @@ 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 +760,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 +771,12 @@ def categories(self) -> Index: >>> ser = pd.Series(raw_cat) >>> ser.cat.categories Index(['b', 'c', 'd'], dtype='object') + + For Categorical: + + >>> cat = pd.Categorical(['a', 'b'], ordered=True) + >>> cat.categories + Index(['a', 'b'], dtype='object') """ return self.dtype.categories @@ -769,6 +787,9 @@ def ordered(self) -> Ordered: Examples -------- + + For Series: + >>> ser = pd.Series(["a", "b", "c", "a"], dtype="category") >>> ser.cat.ordered False @@ -777,6 +798,16 @@ def ordered(self) -> Ordered: >>> ser = pd.Series(raw_cat) >>> ser.cat.ordered True + + For Categorical: + + >>> cat = pd.Categorical(['a', 'b'], ordered=True) + >>> cat.ordered + True + + >>> cat = pd.Categorical(['a', 'b'], ordered=False) + >>> cat.ordered + False """ return self.dtype.ordered @@ -795,6 +826,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 @@ -1492,6 +1529,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: 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/arrays/timedeltas.py b/pandas/core/arrays/timedeltas.py index bf62c327de2f0..2516e687cdbab 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.TimedeltaArray(pd.TimedeltaIndex(['1H', '2H'])) + + ['0 days 01:00:00', '0 days 02:00:00'] + Length: 2, dtype: timedelta64[ns] """ _typ = "timedeltaarray" diff --git a/pandas/core/dtypes/dtypes.py b/pandas/core/dtypes/dtypes.py index c1d3188471aef..50fc5231a3a76 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