diff --git a/doc/source/reference/series.rst b/doc/source/reference/series.rst index 6006acc8f5e16..d0d1ca6c85c31 100644 --- a/doc/source/reference/series.rst +++ b/doc/source/reference/series.rst @@ -107,6 +107,15 @@ Binary operator functions Series.product Series.dot +Unary operator functions +------------------------ +.. autosummary:: + :toctree: api/ + + Series.__invert__ + + + Function application, GroupBy & window -------------------------------------- .. autosummary:: diff --git a/doc/source/user_guide/indexing.rst b/doc/source/user_guide/indexing.rst index ebd1791c0f4ad..413ddb7a23155 100644 --- a/doc/source/user_guide/indexing.rst +++ b/doc/source/user_guide/indexing.rst @@ -811,6 +811,10 @@ evaluate an expression such as ``df['A'] > 2 & df['B'] < 3`` as ``df['A'] > (2 & df['B']) < 3``, while the desired evaluation order is ``(df['A'] > 2) & (df['B'] < 3)``. +For toggling boolean masks with the ``~`` operator, see +:meth:`pandas.Series.__invert__`. + + Using a boolean vector to index a Series works exactly as in a NumPy ndarray: .. ipython:: python diff --git a/pandas/core/ops/docstrings.py b/pandas/core/ops/docstrings.py index 5ce0a2da86f31..f3107de94b4de 100644 --- a/pandas/core/ops/docstrings.py +++ b/pandas/core/ops/docstrings.py @@ -781,3 +781,41 @@ def make_flex_doc(op_name: str, typ: str) -> str: B True False C True False """ + +# --- add at bottom of pandas/core/ops/docstrings.py --- + +_doc_series_invert = """ +Bitwise NOT (``~``). + +For boolean dtype, behaves as logical NOT. Missing values (``NA``) propagate. +For integer dtypes, performs bitwise inversion (two's complement) elementwise. + +Returns +------- +Series + Elementwise result with the same index and name. + +Notes +----- +On ``boolean[pyarrow]`` dtype, ``NA`` values also propagate under ``~``. + +See Also +-------- +Series.__and__, Series.__or__, Series.__xor__ + +Examples +-------- +>>> s = pd.Series([True, False, pd.NA], dtype="boolean") +>>> ~s +0 False +1 True +2 +dtype: boolean + +>>> s = pd.Series([1, 2, -3], dtype="Int32") +>>> ~s +0 -2 +1 -3 +2 2 +dtype: Int32 +""" diff --git a/pandas/core/series.py b/pandas/core/series.py index a5c3bb8d51e8a..ee59b249401d4 100644 --- a/pandas/core/series.py +++ b/pandas/core/series.py @@ -7338,3 +7338,7 @@ def cumsum(self, axis: Axis = 0, skipna: bool = True, *args, **kwargs) -> Self: @doc(make_doc("cumprod", 1)) def cumprod(self, axis: Axis = 0, skipna: bool = True, *args, **kwargs) -> Self: return NDFrame.cumprod(self, axis, skipna, *args, **kwargs) + +# at bottom of pandas/core/series.py (after class Series ...) +from pandas.core.ops.docstrings import _doc_series_invert +Series.__invert__.__doc__ = _doc_series_invert