From 33298bf27b1d852878eeb496974e2d14091143ea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Tue, 23 May 2023 13:56:20 +0200 Subject: [PATCH 1/2] DOC Added Index examples Index.drop, identical, insert DOC: Fixing EX01 - Added examples (#53336) * Examples * Changed Index.copy * Corrected Float32Dtype & Float64Dtype Added is_, take, putmask, unique --- ci/code_checks.sh | 14 -------- pandas/core/arrays/floating.py | 14 ++++++++ pandas/core/arrays/interval.py | 27 ++++++++++++--- pandas/core/base.py | 14 ++++++++ pandas/core/indexes/base.py | 62 ++++++++++++++++++++++++++++++++++ 5 files changed, 113 insertions(+), 18 deletions(-) diff --git a/ci/code_checks.sh b/ci/code_checks.sh index 4eecee4be4731..962e7cc86a98b 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -170,8 +170,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.Period.asfreq \ pandas.Period.now \ pandas.arrays.PeriodArray \ - pandas.arrays.IntervalArray.from_arrays \ - pandas.arrays.IntervalArray.to_tuples \ pandas.Int8Dtype \ pandas.Int16Dtype \ pandas.Int32Dtype \ @@ -181,8 +179,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.UInt32Dtype \ pandas.UInt64Dtype \ pandas.NA \ - pandas.Float32Dtype \ - pandas.Float64Dtype \ pandas.CategoricalDtype.categories \ pandas.CategoricalDtype.ordered \ pandas.Categorical.dtype \ @@ -258,16 +254,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then pandas.util.hash_pandas_object \ pandas_object \ pandas.api.interchange.from_dataframe \ - pandas.Index.T \ - pandas.Index.memory_usage \ - pandas.Index.copy \ - pandas.Index.drop \ - pandas.Index.identical \ - pandas.Index.insert \ - pandas.Index.is_ \ - pandas.Index.take \ - pandas.Index.putmask \ - pandas.Index.unique \ pandas.Index.fillna \ pandas.Index.dropna \ pandas.Index.astype \ diff --git a/pandas/core/arrays/floating.py b/pandas/core/arrays/floating.py index c268b25bf4a59..bd3c03f9218d4 100644 --- a/pandas/core/arrays/floating.py +++ b/pandas/core/arrays/floating.py @@ -134,6 +134,20 @@ class FloatingArray(NumericArray): Methods ------- None + +Examples +-------- +For Float32Dtype: + +>>> ser = pd.Series([2.25, pd.NA], dtype=pd.Float32Dtype()) +>>> ser.dtype +Float32Dtype() + +For Float64Dtype: + +>>> ser = pd.Series([2.25, pd.NA], dtype=pd.Float64Dtype()) +>>> ser.dtype +Float64Dtype() """ # create the Dtype diff --git a/pandas/core/arrays/interval.py b/pandas/core/arrays/interval.py index 2303f8334c07c..2842d8267b7c6 100644 --- a/pandas/core/arrays/interval.py +++ b/pandas/core/arrays/interval.py @@ -509,6 +509,8 @@ def from_breaks( "name": "", "examples": textwrap.dedent( """\ + Examples + -------- >>> pd.arrays.IntervalArray.from_arrays([0, 1, 2], [1, 2, 3]) [(0, 1], (1, 2], (2, 3]] @@ -1635,9 +1637,8 @@ def __arrow_array__(self, type=None): return pyarrow.ExtensionArray.from_storage(interval_type, storage_array) - _interval_shared_docs[ - "to_tuples" - ] = """ + _interval_shared_docs["to_tuples"] = textwrap.dedent( + """ Return an %(return_type)s of tuples of the form (left, right). Parameters @@ -1651,9 +1652,27 @@ def __arrow_array__(self, type=None): tuples: %(return_type)s %(examples)s\ """ + ) @Appender( - _interval_shared_docs["to_tuples"] % {"return_type": "ndarray", "examples": ""} + _interval_shared_docs["to_tuples"] + % { + "return_type": "ndarray", + "examples": textwrap.dedent( + """\ + + Examples + -------- + >>> idx = pd.arrays.IntervalArray.from_tuples([(0, 1), (1, 2)]) + >>> idx + + [(0, 1], (1, 2]] + Length: 2, dtype: interval[int64, right] + >>> idx.to_tuples() + array([(0, 1), (1, 2)], dtype=object) + """ + ), + } ) def to_tuples(self, na_tuple: bool = True) -> np.ndarray: tuples = com.asarray_tuplesafe(zip(self._left, self._right)) diff --git a/pandas/core/base.py b/pandas/core/base.py index d939c0d454de8..0d99118d25e96 100644 --- a/pandas/core/base.py +++ b/pandas/core/base.py @@ -300,6 +300,8 @@ def transpose(self, *args, **kwargs) -> Self: Examples -------- + For Series: + >>> s = pd.Series(['Ant', 'Bear', 'Cow']) >>> s 0 Ant @@ -311,6 +313,12 @@ def transpose(self, *args, **kwargs) -> Self: 1 Bear 2 Cow dtype: object + + For Index: + + >>> idx = pd.Index([1, 2, 3]) + >>> idx.T + Index([1, 2, 3], dtype='int64') """, ) @@ -1088,6 +1096,12 @@ def _memory_usage(self, deep: bool = False) -> int: ----- Memory usage does not include memory consumed by elements that are not components of the array if deep=False or if used on PyPy + + Examples + -------- + >>> idx = pd.Index([1, 2, 3]) + >>> idx.memory_usage() + 24 """ if hasattr(self.array, "memory_usage"): return self.array.memory_usage( # pyright: ignore[reportGeneralTypeIssues] diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index e7d975068dd70..870c78e06aeb0 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -799,6 +799,18 @@ def is_(self, other) -> bool: See Also -------- Index.identical : Works like ``Index.is_`` but also checks metadata. + + Examples + -------- + >>> idx1 = pd.Index(['1', '2', '3']) + >>> idx2 = pd.Index(['1', '2', '3']) + >>> idx2.is_(idx1) + False + + >>> idx1 = pd.Index(['1', '2', '3']) + >>> new_name = idx1 + >>> new_name.is_(idx1) + True """ if self is other: return True @@ -1089,6 +1101,12 @@ def astype(self, dtype, copy: bool = True): -------- numpy.ndarray.take: Return an array formed from the elements of a at the given indices. + + Examples + -------- + >>> idx = pd.Index(['a', 'b', 'c']) + >>> idx.take([2]) + Index(['c'], dtype='object') """ @Appender(_index_shared_docs["take"] % _index_doc_kwargs) @@ -1221,6 +1239,13 @@ def copy( ----- In most cases, there should be no functional difference from using ``deep``, but if ``deep`` is passed it will attempt to deepcopy. + + Examples + -------- + >>> idx = pd.Index(['a', 'b', 'c']) + >>> new_idx = idx.copy() + >>> idx is new_idx + False """ name = self._validate_names(name=name, deep=deep)[0] @@ -2959,6 +2984,12 @@ def unique(self, level: Hashable | None = None) -> Self: -------- unique : Numpy array of unique values in that column. Series.unique : Return unique values of Series object. + + Examples + -------- + >>> idx = pd.Index([1, 1, 2, 3, 3]) + >>> idx.unique() + Index([1, 2, 3], dtype='int64') """ if level is not None: self._validate_index_level(level) @@ -5338,6 +5369,13 @@ def putmask(self, mask, value) -> Index: -------- numpy.ndarray.putmask : Changes elements of an array based on conditional and input values. + + Examples + -------- + >>> idx1 = pd.Index([1, 2, 3]) + >>> idx2 = pd.Index([5, 6, 7]) + >>> idx1.putmask([True, False, False], idx2) + Index([5, 2, 3], dtype='int64') """ mask, noop = validate_putmask(self._values, mask) if noop: @@ -5467,6 +5505,18 @@ def identical(self, other) -> bool: bool If two Index objects have equal elements and same type True, otherwise False. + + Examples + -------- + >>> idx1 = pd.Index(['1', '2', '3']) + >>> idx2 = pd.Index(['1', '2', '3']) + >>> idx2.identical(idx1) + True + + >>> idx1 = pd.Index(['1', '2', '3'], name="A") + >>> idx2 = pd.Index(['1', '2', '3'], name="B") + >>> idx2.identical(idx1) + False """ return ( self.equals(other) @@ -6687,6 +6737,12 @@ def insert(self, loc: int, item) -> Index: Returns ------- Index + + Examples + -------- + >>> idx = pd.Index(['a', 'b', 'c']) + >>> idx.insert(1, 'x') + Index(['a', 'x', 'b', 'c'], dtype='object') """ item = lib.item_from_zerodim(item) if is_valid_na_for_dtype(item, self.dtype) and self.dtype != object: @@ -6748,6 +6804,12 @@ def drop( ------ KeyError If not all of the labels are found in the selected axis + + Examples + -------- + >>> idx = pd.Index(['a', 'b', 'c']) + >>> idx.drop(['a']) + Index(['b', 'c'], dtype='object') """ if not isinstance(labels, Index): # avoid materializing e.g. RangeIndex From 5205e9ce501440a60bcefb82ccb0abdc2a61a6c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dea=20Mar=C3=ADa=20L=C3=A9on?= Date: Wed, 24 May 2023 13:57:46 +0200 Subject: [PATCH 2/2] Modified Index.is_ and take examples --- pandas/core/indexes/base.py | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index 870c78e06aeb0..aa8bfb667f5be 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -803,14 +803,11 @@ def is_(self, other) -> bool: Examples -------- >>> idx1 = pd.Index(['1', '2', '3']) - >>> idx2 = pd.Index(['1', '2', '3']) - >>> idx2.is_(idx1) - False - - >>> idx1 = pd.Index(['1', '2', '3']) - >>> new_name = idx1 - >>> new_name.is_(idx1) + >>> idx1.is_(idx1.view()) True + + >>> idx1.is_(idx1.copy()) + False """ if self is other: return True @@ -1105,8 +1102,8 @@ def astype(self, dtype, copy: bool = True): Examples -------- >>> idx = pd.Index(['a', 'b', 'c']) - >>> idx.take([2]) - Index(['c'], dtype='object') + >>> idx.take([2, 2, 1, 2]) + Index(['c', 'c', 'b', 'c'], dtype='object') """ @Appender(_index_shared_docs["take"] % _index_doc_kwargs)