[docs] [issue29710] Incorrect representation caveat on bitwise operation docs

[Nick Coghlan]

Nick Coghlan <ncoghlan at gmail.com> added the comment:

Right, and that's why I think we're better off focusing on the arithmetic explanations wherever they apply. The problem is that for "x | y" and "x & y" there's no avoiding discussing the 2's complement representation.

Martin, would you find the reference to `bit_length()` in the current PR easier to follow if it had a second follow-up sentence like the one below:

===
Bitwise binary operations are semantically equivalent to calculations
using 2's complement in a bit-width of ``1 + max(x.bit_length(), y
.bit_length()``. This choice of bit-width ensures there is sufficient space for the absolute value of both operands, while also providing space for an explicit sign bit (representing the conceptually infinite series of zeros or ones at the left of a 2's complement value).
===

That retains the precision of the currently suggested definition (for the benefit of language implementors), but also spells out the rationale for that definition (the "1 +" is for the sign bit, while the abs() is implicit in the fact that bit_length() assumes 2's complement and hence doesn't allow space for an explicit sign bit).

----------

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue29710>
_______________________________________