diff --git a/ci/code_checks.sh b/ci/code_checks.sh index a9967dcb8efe6..5e5391ae8111c 100755 --- a/ci/code_checks.sh +++ b/ci/code_checks.sh @@ -191,7 +191,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.Index.dropna RT03,SA01" \ -i "pandas.Index.dtype SA01" \ -i "pandas.Index.duplicated RT03" \ - -i "pandas.Index.empty GL08" \ -i "pandas.Index.equals SA01" \ -i "pandas.Index.fillna RT03" \ -i "pandas.Index.get_indexer PR07,SA01" \ @@ -209,7 +208,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.Index.map SA01" \ -i "pandas.Index.memory_usage RT03" \ -i "pandas.Index.name SA01" \ - -i "pandas.Index.names GL08" \ -i "pandas.Index.nbytes SA01" \ -i "pandas.Index.ndim SA01" \ -i "pandas.Index.nunique RT03" \ @@ -227,7 +225,6 @@ if [[ -z "$CHECK" || "$CHECK" == "docstrings" ]]; then -i "pandas.Index.union PR07,RT03,SA01" \ -i "pandas.Index.unique RT03" \ -i "pandas.Index.value_counts RT03" \ - -i "pandas.Index.view GL08" \ -i "pandas.Int16Dtype SA01" \ -i "pandas.Int32Dtype SA01" \ -i "pandas.Int64Dtype SA01" \ diff --git a/pandas/core/base.py b/pandas/core/base.py index 33b37319675ae..a889416f8ec86 100644 --- a/pandas/core/base.py +++ b/pandas/core/base.py @@ -675,6 +675,33 @@ def to_numpy( @final @property def empty(self) -> bool: + """ + Check if the Index is empty. + + An Index is considered empty if it has no elements. This property can be + useful for quickly checking the state of an Index, especially in data + processing and analysis workflows where handling of empty datasets might + be required. + + Returns + ------- + bool + ``True`` if the Index is empty, ``False`` otherwise. + + See Also + -------- + Index.size : Return the number of elements in the Index. + + Examples + -------- + >>> index = pd.Index([]) + >>> index.empty + True + + >>> non_empty_index = pd.Index([1, 2, 3]) + >>> non_empty_index.empty + False + """ return not self.size @doc(op="max", oppose="min", value="largest") diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py index c2df773326dc9..bbb2f1dc79506 100644 --- a/pandas/core/indexes/base.py +++ b/pandas/core/indexes/base.py @@ -1011,6 +1011,53 @@ def ravel(self, order: str_t = "C") -> Self: return self[:] def view(self, cls=None): + """ + Return a view of the Index with the specified dtype or a new Index instance. + + This method returns a view of the calling Index object if no arguments are + provided. If a dtype is specified through the `cls` argument, it attempts + to return a view of the Index with the specified dtype. Note that viewing + the Index as a different dtype reinterprets the underlying data, which can + lead to unexpected results for non-numeric or incompatible dtype conversions. + + Parameters + ---------- + cls : dtype, optional + The dtype for the returned view of the Index. If ``None`` (default), a view + of the calling Index is returned without altering the dtype. If a numeric + dtype is specified, the method attempts to reinterpret the Index data as + the specified dtype. + + Returns + ------- + Index or ndarray + A view of the Index. If `cls` is None, the returned object is an Index + view with the same dtype as the calling object. If a numeric `cls` is + specified an ndarray view with the new dtype is returned. + + Raises + ------ + ValueError + If attempting to change to a dtype in a way that is not compatible with + the original dtype's memory layout, for example, viewing an 'int64' Index + as 'str'. + + See Also + -------- + Index.copy : Returns a copy of the Index. + + Examples + -------- + >>> idx = pd.Index([1, 2, 3]) + >>> idx.view() + Index([1, 2, 3], dtype='int64') + + Viewing as 'int32' reinterprets the memory, which may lead to unexpected + behavior: + + >>> idx.view("int32") + array([1, 0, 2, 0, 3, 0], dtype=int32) + """ # we need to see if we are subclassing an # index type here if cls is not None and not hasattr(cls, "_typ"): @@ -1735,6 +1782,37 @@ def _get_default_index_names( return names def _get_names(self) -> tuple[Hashable | None, ...]: + """ + Retrieve the names associated with the object. + + This method returns a tuple containing the name of the object. + It's primarily intended for internal use. + + Returns + ------- + tuple[Hashable | None, ...] + A tuple containing the object's name, or None if the object does not have a + name. + + See Also + -------- + Index.name : Index name as a string instead of a tuple, or None for MultiIndex. + Series.name : Series name. + + Examples + -------- + Create an index with a name and retrieve its names: + + >>> index = pd.Index([1, 2, 3], name="example_name") + >>> index.names + ('example_name',) + + If the index does not have a name set: + + >>> index = pd.Index([1, 2, 3]) + >>> index.names + (None,) + """ return (self.name,) def _set_names(self, values, *, level=None) -> None: