From 8e9207f7acc80dbd36cf6c420ee7306a96eb3c15 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Wed, 19 Jul 2023 20:35:44 +0200 Subject: [PATCH] Examples ExtensionArray.dropna... --- ci/code_checks.sh | 10 ----- pandas/core/arrays/base.py | 77 +++++++++++++++++++++++++++++++++++++- 2 files changed, 76 insertions(+), 11 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index bb2dacd2ead61..ef599afa12841 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -115,18 +115,8 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.api.extensions.ExtensionArray._hash_pandas_object \ pandas.api.extensions.ExtensionArray._reduce \ pandas.api.extensions.ExtensionArray._values_for_factorize \ - pandas.api.extensions.ExtensionArray.dropna \ - pandas.api.extensions.ExtensionArray.equals \ - pandas.api.extensions.ExtensionArray.factorize \ - pandas.api.extensions.ExtensionArray.fillna \ - pandas.api.extensions.ExtensionArray.insert \ pandas.api.extensions.ExtensionArray.interpolate \ - pandas.api.extensions.ExtensionArray.isin \ - pandas.api.extensions.ExtensionArray.isna \ pandas.api.extensions.ExtensionArray.ravel \ - pandas.api.extensions.ExtensionArray.searchsorted \ - pandas.api.extensions.ExtensionArray.shift \ - pandas.api.extensions.ExtensionArray.unique \ pandas.api.extensions.ExtensionArray.ndim \ pandas.api.extensions.ExtensionArray.shape \ pandas.api.extensions.ExtensionArray.tolist \ diff --git a/pandas/core/arrays/base.py b/pandas/core/arrays/base.py index 34b2f03681c6a..ca95451575af5 100644 --- a/pandas/core/arrays/base.py +++ b/pandas/core/arrays/base.py @@ -656,6 +656,12 @@ def isna(self) -> np.ndarray | ExtensionArraySupportsAnyAll: * ``na_values._is_boolean`` should be True * `na_values` should implement :func:`ExtensionArray._reduce` * ``na_values.any`` and ``na_values.all`` should be implemented + + Examples + -------- + >>> arr = pd.array([1, 2, np.nan, np.nan]) + >>> arr.isna() + array([False, False, True, True]) """ raise AbstractMethodError(self) @@ -882,6 +888,14 @@ def fillna( ------- ExtensionArray With NA/NaN filled. + + Examples + -------- + >>> arr = pd.array([np.nan, np.nan, 2, 3, np.nan, np.nan]) + >>> arr.fillna(0) + + [0, 0, 2, 3, 0, 0] + Length: 6, dtype: Int64 """ value, method = validate_fillna_kwargs(value, method) @@ -918,7 +932,13 @@ def dropna(self) -> Self: Returns ------- - pandas.api.extensions.ExtensionArray + + Examples + -------- + >>> pd.array([1, 2, np.nan]).dropna() + + [1, 2] + Length: 2, dtype: Int64 """ # error: Unsupported operand type for ~ ("ExtensionArray") return self[~self.isna()] # type: ignore[operator] @@ -955,6 +975,14 @@ def shift(self, periods: int = 1, fill_value: object = None) -> ExtensionArray: ``self.dtype.na_value``. For 2-dimensional ExtensionArrays, we are always shifting along axis=0. + + Examples + -------- + >>> arr = pd.array([1, 2, 3]) + >>> arr.shift(2) + + [, , 1] + Length: 3, dtype: Int64 """ # Note: this implementation assumes that `self.dtype.na_value` can be # stored in an instance of your ExtensionArray with `self.dtype`. @@ -982,6 +1010,14 @@ def unique(self) -> Self: Returns ------- pandas.api.extensions.ExtensionArray + + Examples + -------- + >>> arr = pd.array([1, 2, 3, 1, 2, 3]) + >>> arr.unique() + + [1, 2, 3] + Length: 3, dtype: Int64 """ uniques = unique(self.astype(object)) return self._from_sequence(uniques, dtype=self.dtype) @@ -1029,6 +1065,12 @@ def searchsorted( See Also -------- numpy.searchsorted : Similar method from NumPy. + + Examples + -------- + >>> arr = pd.array([1, 2, 3, 5]) + >>> arr.searchsorted([4]) + array([3]) """ # Note: the base tests provided by pandas only test the basics. # We do not test @@ -1057,6 +1099,13 @@ def equals(self, other: object) -> bool: ------- boolean Whether the arrays are equivalent. + + Examples + -------- + >>> arr1 = pd.array([1, 2, np.nan]) + >>> arr2 = pd.array([1, 2, np.nan]) + >>> arr1.equals(arr2) + True """ if type(self) != type(other): return False @@ -1087,6 +1136,14 @@ def isin(self, values) -> npt.NDArray[np.bool_]: Returns ------- np.ndarray[bool] + + Examples + -------- + >>> arr = pd.array([1, 2, 3]) + >>> arr.isin([1]) + + [True, False, False] + Length: 3, dtype: boolean """ return isin(np.asarray(self), values) @@ -1151,6 +1208,16 @@ def factorize( Notes ----- :meth:`pandas.factorize` offers a `sort` keyword as well. + + Examples + -------- + >>> idx1 = pd.PeriodIndex(["2014-01", "2014-01", "2014-02", "2014-02", + ... "2014-03", "2014-03"], freq="M") + >>> arr, idx = idx1.factorize() + >>> arr + array([0, 0, 1, 1, 2, 2]) + >>> idx + PeriodIndex(['2014-01', '2014-02', '2014-03'], dtype='period[M]') """ # Implementer note: There are two ways to override the behavior of # pandas.factorize @@ -1657,6 +1724,14 @@ def insert(self, loc: int, item) -> Self: The default implementation relies on _from_sequence to raise on invalid items. + + Examples + -------- + >>> arr = pd.array([1, 2, 3]) + >>> arr.insert(2, -1) + + [1, 2, -1, 3] + Length: 4, dtype: Int64 """ loc = validate_insert_loc(loc, len(self))