Feature Type

  • [ ] Adding new functionality to pandas

  • [X] Changing existing functionality in pandas

  • [ ] Removing existing functionality in pandas

Problem Description

pandas.isnull is an alias of the pandas.isna as below. However, there is no code-level docstring on pandas.isnull.

# pandas/pandas/core/dtypes/missing.py
# below code describes line 108 ~ 188

...

def isna(obj: object) -> bool | npt.NDArray[np.bool_] | NDFrame:
    """
    Detect missing values for an array-like object.
    ...
    """
    ...
    return _isna(obj)


isnull = isna

...

We can find similar pattern on the relationship between DataFrame.isnull and DataFrame.isna. In this case, DataFrame.isnull has right docstring and is defined as well-constructed method at the same time.

# pandas/pandas/core/frame.py
# below code describes line 6224 ~ 6228

...

    @doc(NDFrame.isna, klass=_shared_doc_kwargs["klass"])
    def isnull(self) -> DataFrame:
        """
        DataFrame.isnull is an alias for DataFrame.isna.
        """
        return self.isna()

...

Feature Description

Instead of isnull = isna, define pandas.isnull as a function with docstring.

# on pandas/pandas/core/dtypes/missing.py

...

def isnull(obj: object) -> bool | npt.NDArray[np.bool_] | NDFrame:
    """
    pandas.isnull is an alias for pandas.isna.
    """
    return isna(obj)

...

Alternative Solutions

An alternative solution is to indicate in the docstring that pandas.isnull is an alias of the pandas.isna.

Additional Context

No response

Comment From: MarcoGorelli

Hi @Fitree

Looks like the docstring shows up fine here https://pandas.pydata.org/docs/dev/reference/api/pandas.isnull.html ? Could you clarify please?

Comment From: phofl

Yes this is shared docstring and works as intended.

Comment From: Fitree

Thanks for the reply. If this is intended, it's okay to close this issue.

@MarcoGorelli
More clealy, my suggestion was to add some docstring that indicates np.isnull is alias of the np.isna. On the docstring of the padnas.DataFrame.isnull, it indicates that pandas.DataFrame.isnull is an alias for pandas.DataFrame.isna. It expains clearly what Dataframe.isnull is.

DataFrame.isnull is an alias for DataFrame.isna.

Detect missing values.

Return a boolean same-sized object indicating if the values are NA. NA values, ...

The resason I suggest this is based on my experience. Since there is no clue about this fact (pd.isnull is an alias for pd.isna), I was confused on which one to use and worried they would work differently.

Again, if you think this work is over engineering, I'm okay with closing this issue :)