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: python#82012 (comment)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

This also pulls the bool type to top-level of the type
description page. Before it was only documented in the
section "Other Built-in Types / Boolean Values".

This was referenced

pllim added a commit to pllim/cpython that referenced this pull request