DOC: Fixing EX01 - Added examples (#53796)

* examples TimedeltaArray, Period.asfreq

* Examples for categoricals

* Exampl Categorical.codes and .__array__, edited code_checks

* Corrected TimedeltaArray and wording to categorical

* remove multiline

---------

Co-authored-by: MarcoGorelli <[email protected]>

Author: DeaMariaLeon

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 \

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)
 

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:

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'))
+    <PeriodArray>
+    ['2023-01-01', '2023-01-02']
+    Length: 2, dtype: period[D]
     """
 
     # array priority higher than numpy scalars

pandas/core/arrays/timedeltas.py

@@ -132,6 +132,13 @@ class TimedeltaArray(dtl.TimelikeOps):
     Methods
     -------
     None
+
+    Examples
+    --------
+    >>> pd.arrays.TimedeltaArray(pd.TimedeltaIndex(['1H', '2H']))
+    <TimedeltaArray>
+    ['0 days 01:00:00', '0 days 02:00:00']
+    Length: 2, dtype: timedelta64[ns]
     """
 
     _typ = "timedeltaarray"

pandas/core/dtypes/dtypes.py

@@ -610,13 +610,29 @@ 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
 
     @property
     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