gh-82012: Deprecate bitwise inversion (~) of bool

The bitwise inversion operator on bool returns the bitwise inversion of the
underlying int value; i.e. `~True == -2` such that `bool(~True) == True`.

It's a common pitfall that users mistake `~` as negation operator and actually
want `not`. Supporting `~` is an artifact of bool inheriting from int. Since there
is no real use-case for the current behavior, let's deprecate `~` on bool and
later raise an error. This removes a potential source errors for users.

Full reasoning: #82012 (comment)

📜🤖 Added by blurb_it.

Co-authored-by: Jelle Zijlstra <[email protected]>

Author: timhoffm

Doc/whatsnew/3.12.rst

@@ -705,6 +705,14 @@ Deprecated
   replaced by :data:`calendar.Month.JANUARY` and :data:`calendar.Month.FEBRUARY`.
   (Contributed by Prince Roshan in :gh:`103636`.)
 
+* The bitwise inversion operator (~) on bool is deprecated. It will throw an
+
+* The bitwise inversion operator (``~``) on bool is deprecated. It will throw an
+  error in Python 3.14. Use ``not`` for logical negation of bools instead.
+  In the rare case that you really need the bitwise inversion of the underlying
+  ``int``, convert to int explicitly with ``~int(x)``. (Contributed by Tim Hoffmann
+  in :gh:`103487`.)
+
 Pending Removal in Python 3.13
 ------------------------------
 

Lib/test/test_bool.py

@@ -58,8 +58,22 @@ def test_math(self):
         self.assertEqual(-True, -1)
         self.assertEqual(abs(True), 1)
         self.assertIsNot(abs(True), True)
-        self.assertEqual(~False, -1)
-        self.assertEqual(~True, -2)
+        with self.assertWarns(DeprecationWarning):
+            # We need to put the bool in a variable, because the constant
+            # ~False is evaluated at compile time due to constant folding;
+            # consequently the DeprecationWarning would be issued during
+            # module loading and not during test execution.
+            false = False
+            self.assertEqual(~false, -1)
+        with self.assertWarns(DeprecationWarning):
+            # also check that the warning is issued in case of constant
+            # folding at compile time
+            self.assertEqual(eval("~False"), -1)
+        with self.assertWarns(DeprecationWarning):
+            true = True
+            self.assertEqual(~true, -2)
+        with self.assertWarns(DeprecationWarning):
+            self.assertEqual(eval("~True"), -2)
 
         self.assertEqual(False+2, 2)
         self.assertEqual(True+2, 3)

Misc/NEWS.d/next/Core and Builtins/2023-04-12-19-55-24.gh-issue-82012.FlcJAh.rst

@@ -0,0 +1,5 @@
+The bitwise inversion operator (~) on bool is deprecated.
+It returns the bitwise inversion of the underlying ``int`` representation such that
+``bool(~True) == True``, which can be confusing. Use ``not`` for logical negation
+of bools. In the rare case that you really need the bitwise inversion of the underlying ``int``,
+convert to int explicitly ``~int(x)``.

Objects/boolobject.c

@@ -73,6 +73,22 @@ bool_vectorcall(PyObject *type, PyObject * const*args,
 
 /* Arithmetic operations redefined to return bool if both args are bool. */
 
+static PyObject *
+bool_invert(PyObject *v)
+{
+    if (PyErr_WarnEx(PyExc_DeprecationWarning,
+                     "Bitwise inversion '~' on bool is deprecated. This "
+                     "returns the bitwise inversion of the underlying int "
+                     "object and is usually not what you expect from negating "
+                     "a bool. Use the 'not' operator for boolean negation or "
+                     "~int(x) if you really want the bitwise inversion of the "
+                     "underlying int.",
+                     1) < 0) {
+        return NULL;
+    }
+    return PyLong_Type.tp_as_number->nb_invert(v);
+}
+
 static PyObject *
 bool_and(PyObject *a, PyObject *b)
 {
@@ -119,7 +135,7 @@ static PyNumberMethods bool_as_number = {
     0,                          /* nb_positive */
     0,                          /* nb_absolute */
     0,                          /* nb_bool */
-    0,                          /* nb_invert */
+    (unaryfunc)bool_invert,     /* nb_invert */
     0,                          /* nb_lshift */
     0,                          /* nb_rshift */
     bool_and,                   /* nb_and */