From 12561edbb8a7673a134cbe479636990fbbf45b8e Mon Sep 17 00:00:00 2001 From: rlawnsrl123 Date: Fri, 10 Oct 2025 00:19:06 +0900 Subject: [PATCH 1/9] Create pandas.Series.__invert__.rst --- .../api/pandas.Series.__invert__.rst | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 doc/source/reference/api/pandas.Series.__invert__.rst diff --git a/doc/source/reference/api/pandas.Series.__invert__.rst b/doc/source/reference/api/pandas.Series.__invert__.rst new file mode 100644 index 0000000000000..e7586c6a3b813 --- /dev/null +++ b/doc/source/reference/api/pandas.Series.__invert__.rst @@ -0,0 +1,48 @@ +.. currentmodule:: pandas + +pandas.Series.__invert__ +======================== + +Elementwise invert (``~``) for :class:`pandas.Series`. + +**Signature** + ``Series.__invert__(self) -> Series`` + +**Summary** + For boolean and nullable-boolean dtypes, ``~s`` toggles the mask + (``True`` ↔ ``False``) and propagates ``pd.NA``. For integer dtypes, + ``~`` performs bitwise invert as in Python. + +**Examples** + +Boolean / nullable boolean:: + + >>> s = pd.Series([True, pd.NA, False], dtype="boolean") + >>> ~s + 0 False + 1 + 2 True + dtype: boolean + +Integer vs boolean:: + + >>> s_int = pd.Series([0, 1, 2], dtype="int64") + >>> ~s_int + 0 -1 + 1 -2 + 2 -3 + dtype: int64 + +Arrow-backed boolean (if pyarrow installed):: + + >>> s_arrow = pd.Series([True, pd.NA, False], dtype="boolean[pyarrow]") + >>> ~s_arrow + 0 False + 1 + 2 True + dtype: boolean[pyarrow] + +**Notes** +* In Python’s stdlib, :func:`operator.__invert__` is bitwise invert on integers. + In pandas, ``~`` on boolean arrays is elementwise invert. +* See also :ref:`user_guide.boolean_indexing`. From e34048db4bf2030ac52def653f2232ad499c2b1b Mon Sep 17 00:00:00 2001 From: rlawnsrl123 Date: Fri, 10 Oct 2025 00:28:22 +0900 Subject: [PATCH 2/9] DOC: add unary operator section; link Series.__invert__ --- doc/source/reference/series.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/source/reference/series.rst b/doc/source/reference/series.rst index 6006acc8f5e16..a099c48613e21 100644 --- a/doc/source/reference/series.rst +++ b/doc/source/reference/series.rst @@ -107,6 +107,14 @@ Binary operator functions Series.product Series.dot +Unary operator functions +------------------------ +.. toctree:: + :maxdepth: 1 + + api/pandas.Series.__invert__ + + Function application, GroupBy & window -------------------------------------- .. autosummary:: From 10ba2d2bd2051c9a0014c3cbe10c179d8a7e5c9f Mon Sep 17 00:00:00 2001 From: rlawnsrl123 Date: Fri, 10 Oct 2025 00:35:03 +0900 Subject: [PATCH 3/9] DOC: Add docs for Series.__invert__ (~); add cross-link from Boolean indexing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add dedicated API page for Series.__invert__() so searches for “invert/~” find it. --- doc/source/user_guide/indexing.rst | 4 ++++ 1 file changed, 4 insertions(+) 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 From ebe43acdb7daa2bec343c365ac1f148bede0e3fb Mon Sep 17 00:00:00 2001 From: rlawnsrl123 Date: Fri, 10 Oct 2025 01:29:07 +0900 Subject: [PATCH 4/9] Update pandas.Series.__invert__.rst --- .../reference/api/pandas.Series.__invert__.rst | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/doc/source/reference/api/pandas.Series.__invert__.rst b/doc/source/reference/api/pandas.Series.__invert__.rst index e7586c6a3b813..53443d60ce668 100644 --- a/doc/source/reference/api/pandas.Series.__invert__.rst +++ b/doc/source/reference/api/pandas.Series.__invert__.rst @@ -6,12 +6,17 @@ pandas.Series.__invert__ Elementwise invert (``~``) for :class:`pandas.Series`. **Signature** - ``Series.__invert__(self) -> Series`` + +``Series.__invert__(self) -> Series`` **Summary** - For boolean and nullable-boolean dtypes, ``~s`` toggles the mask - (``True`` ↔ ``False``) and propagates ``pd.NA``. For integer dtypes, - ``~`` performs bitwise invert as in Python. + +For boolean and nullable-boolean dtypes, ``~s`` toggles the mask +(``True`` ↔ ``False``) and propagates ``pd.NA``. For integer dtypes, +``~`` performs bitwise invert as in Python. + +.. seealso:: + :ref:`indexing.boolean` **Examples** @@ -43,6 +48,6 @@ Arrow-backed boolean (if pyarrow installed):: dtype: boolean[pyarrow] **Notes** -* In Python’s stdlib, :func:`operator.__invert__` is bitwise invert on integers. + +- In Python’s stdlib, :func:`operator.__invert__` is bitwise invert on integers. In pandas, ``~`` on boolean arrays is elementwise invert. -* See also :ref:`user_guide.boolean_indexing`. From 5eb92c655ab044d18fa49c79d9f76d93f91ca71a Mon Sep 17 00:00:00 2001 From: rlawnsrl123 Date: Fri, 10 Oct 2025 02:15:07 +0900 Subject: [PATCH 5/9] Update pandas.Series.__invert__.rst --- doc/source/reference/api/pandas.Series.__invert__.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/source/reference/api/pandas.Series.__invert__.rst b/doc/source/reference/api/pandas.Series.__invert__.rst index 53443d60ce668..0c82307bca351 100644 --- a/doc/source/reference/api/pandas.Series.__invert__.rst +++ b/doc/source/reference/api/pandas.Series.__invert__.rst @@ -16,7 +16,7 @@ For boolean and nullable-boolean dtypes, ``~s`` toggles the mask ``~`` performs bitwise invert as in Python. .. seealso:: - :ref:`indexing.boolean` + :ref:`Boolean indexing ` **Examples** From b1470188372ea1ff473896ad2dcece80c5a4b0fd Mon Sep 17 00:00:00 2001 From: rlawnsrl123 Date: Mon, 20 Oct 2025 16:53:23 +0900 Subject: [PATCH 6/9] DOC : switch series.rst entry to autosummary --- doc/source/reference/series.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/source/reference/series.rst b/doc/source/reference/series.rst index a099c48613e21..d0d1ca6c85c31 100644 --- a/doc/source/reference/series.rst +++ b/doc/source/reference/series.rst @@ -109,10 +109,11 @@ Binary operator functions Unary operator functions ------------------------ -.. toctree:: - :maxdepth: 1 +.. autosummary:: + :toctree: api/ + + Series.__invert__ - api/pandas.Series.__invert__ Function application, GroupBy & window From 2428f9d4469752b79ed6f21edc72e9247c1048fa Mon Sep 17 00:00:00 2001 From: rlawnsrl123 Date: Mon, 20 Oct 2025 16:57:58 +0900 Subject: [PATCH 7/9] DOC: remove manual API page for Series.__invert__ (moved to docstring) --- .../api/pandas.Series.__invert__.rst | 53 ------------------- 1 file changed, 53 deletions(-) delete mode 100644 doc/source/reference/api/pandas.Series.__invert__.rst diff --git a/doc/source/reference/api/pandas.Series.__invert__.rst b/doc/source/reference/api/pandas.Series.__invert__.rst deleted file mode 100644 index 0c82307bca351..0000000000000 --- a/doc/source/reference/api/pandas.Series.__invert__.rst +++ /dev/null @@ -1,53 +0,0 @@ -.. currentmodule:: pandas - -pandas.Series.__invert__ -======================== - -Elementwise invert (``~``) for :class:`pandas.Series`. - -**Signature** - -``Series.__invert__(self) -> Series`` - -**Summary** - -For boolean and nullable-boolean dtypes, ``~s`` toggles the mask -(``True`` ↔ ``False``) and propagates ``pd.NA``. For integer dtypes, -``~`` performs bitwise invert as in Python. - -.. seealso:: - :ref:`Boolean indexing ` - -**Examples** - -Boolean / nullable boolean:: - - >>> s = pd.Series([True, pd.NA, False], dtype="boolean") - >>> ~s - 0 False - 1 - 2 True - dtype: boolean - -Integer vs boolean:: - - >>> s_int = pd.Series([0, 1, 2], dtype="int64") - >>> ~s_int - 0 -1 - 1 -2 - 2 -3 - dtype: int64 - -Arrow-backed boolean (if pyarrow installed):: - - >>> s_arrow = pd.Series([True, pd.NA, False], dtype="boolean[pyarrow]") - >>> ~s_arrow - 0 False - 1 - 2 True - dtype: boolean[pyarrow] - -**Notes** - -- In Python’s stdlib, :func:`operator.__invert__` is bitwise invert on integers. - In pandas, ``~`` on boolean arrays is elementwise invert. From c9fb49b7f68c710c77e2b63103c9ae33c7c73e48 Mon Sep 17 00:00:00 2001 From: rlawnsrl123 Date: Fri, 24 Oct 2025 18:38:24 +0900 Subject: [PATCH 8/9] DOC: add Series.__invert__ docstring template --- pandas/core/ops/docstrings.py | 38 +++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) 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 +""" From fc0415e1da11ac1edcf6ea0b712df02c91707745 Mon Sep 17 00:00:00 2001 From: rlawnsrl123 Date: Fri, 24 Oct 2025 19:18:47 +0900 Subject: [PATCH 9/9] DOC: bind Series.__invert__ to new docstring --- pandas/core/series.py | 4 ++++ 1 file changed, 4 insertions(+) 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