[issue29710] Incorrect representation caveat on bitwise operation docs

miss-islington added the comment: New changeset 3100b7e710dccdcfbc6991ea7e8985a1881d42e6 by Miss Islington (bot) in branch '3.6': bpo-29710: Clarify documentation for Bitwise binary operation (GH-1691) https://github.com/python/cpython/commit/3100b7e710dccdcfbc6991ea7e8985a1881d42e6

[issue29710] Incorrect representation caveat on bitwise operation docs

miss-islington added the comment: New changeset 8764a6ffda896af4586f07b55d7df916f86dd9b0 by Miss Islington (bot) in branch '3.7': bpo-29710: Clarify documentation for Bitwise binary operation (GH-1691) https://github.com/python/cpython/commit/8764a6ffda896af4586f07b55d7df916f86dd9b0

[issue29710] Incorrect representation caveat on bitwise operation docs

Nick Coghlan added the comment: Mark & Tim: thanks for the discussion and clarifications above, I learned some new things myself! Sanyam: thanks for the patch, and for your patience while we figured out what we wanted the new wording to actually say :) (Technically the backport PRs are

[issue29710] Incorrect representation caveat on bitwise operation docs

Change by miss-islington : -- pull_requests: +8026 ___ Python tracker ___ ___ Python-bugs-list mailing list Unsubscribe:

[issue29710] Incorrect representation caveat on bitwise operation docs

Change by miss-islington : -- keywords: +patch pull_requests: +8025 stage: needs patch -> patch review ___ Python tracker ___ ___

[issue29710] Incorrect representation caveat on bitwise operation docs

Nick Coghlan added the comment: New changeset b4bc5cab82e6855e4ebc33ba0b669ddffad30fb3 by Nick Coghlan (Sanyam Khurana) in branch 'master': bpo-29710: Clarify documentation for Bitwise binary operation (GH-1691)

[issue29710] Incorrect representation caveat on bitwise operation docs

Sanyam Khurana added the comment: On, yes, I think I missed the first point, earlier. Thank You! I did the changes. -- ___ Python tracker ___

[issue29710] Incorrect representation caveat on bitwise operation docs

Tim Peters added the comment: Nick suggested two changes on 2018-07-15 (look above). Mark & I agreed about the first change, so it wasn't mentioned again after that. All the rest has been refining the second change. -- ___ Python tracker

[issue29710] Incorrect representation caveat on bitwise operation docs

Sanyam Khurana added the comment: Hey Tim, > @CuriousLearner, does the PR also include Nick's first suggested change? > Here: """ = Bitwise operations only make sense for integers. The result of bitwise operations is calculated as though carried out in two's complement

[issue29710] Incorrect representation caveat on bitwise operation docs

Tim Peters added the comment: @CuriousLearner, does the PR also include Nick's first suggested change? Here: """ 1. Replace the opening paragraph of https://docs.python.org/3/library/stdtypes.html#bitwise-operations-on-integer-types (the one I originally quoted when opening this issue)

[issue29710] Incorrect representation caveat on bitwise operation docs

Sanyam Khurana added the comment: Seems good to me. I've made the changes in the PR. -- ___ Python tracker ___ ___

[issue29710] Incorrect representation caveat on bitwise operation docs

Mark Dickinson added the comment: > 4. Performing these calculations with at least one extra sign extension bit > in a finite two's complement representation (a working bit-width of ``1 + > max(x.bit_length(), y.bit_length()`` or more) is sufficient to get the same > result as if there were

[issue29710] Incorrect representation caveat on bitwise operation docs

Nick Coghlan added the comment: Ah, "the internal representation" was meant to refer a hypothetical representation, rather than literally to CPython's actual implementation, but now that you point it out, I agree my wording is ambiguous. I like Tim's suggested replacement:

[issue29710] Incorrect representation caveat on bitwise operation docs

Tim Peters added the comment: Ya, Mark's got a point there. Perhaps s/the internal/a finite two's complement/ ? -- ___ Python tracker ___

[issue29710] Incorrect representation caveat on bitwise operation docs

Mark Dickinson added the comment: The wording for change 1 looks fine to me. For change 2, the mention of the internal representation is misleading, since the internal representation of (long) integers in current CPython is effectively sign-magnitude, and so there are some shenanigans to

[issue29710] Incorrect representation caveat on bitwise operation docs

Nick Coghlan added the comment: OK, that makes sense to me. Given that, there'd be two changes proposed. 1. Replace the opening paragraph of https://docs.python.org/3/library/stdtypes.html#bitwise-operations-on-integer-types (the one I originally quoted when opening this issue) with the

[issue29710] Incorrect representation caveat on bitwise operation docs

Tim Peters added the comment: Well, all 6 operations "are calculated as though carried out in two's complement with an infinite number of sign bits", so I'd float that part out of the footnote and into the main text. When, e.g., you're thinking of ints _as_ bitstrings, it's essentially

[issue29710] Incorrect representation caveat on bitwise operation docs

Nick Coghlan added the comment: The restriction of the footnote to ``x & y``, ``x | y``, and ``x ^ y`` was going to come from the fact that only those rows in the table will reference the new note. However, it likely makes sense to repeat the relevant expressions in the footnote as well,

[issue29710] Incorrect representation caveat on bitwise operation docs

Tim Peters added the comment: Nick, that seems a decent compromise. "Infinite string of sign bits" is how Guido & I both thought of it when the semantics of longs were first defined, and others in this report apparently find it natural enough too. It also applies to all 6 operations in

[issue29710] Incorrect representation caveat on bitwise operation docs

Nick Coghlan added the comment: I think we have a fairly different notion of what clarity means here - I have no mental concept whatsoever of how to do two's complement arithmetic with an infinite number of sign bits (I learned most of what I know about two's complement by working with

[issue29710] Incorrect representation caveat on bitwise operation docs

Tim Peters added the comment: To answer the old accusation ;-), no, this isn't my wording. I _always_ explain that Python's integer bit operations act as if the integers were stored in 2's-complement representation but with an infinite number of sign bits. That's all.

[issue29710] Incorrect representation caveat on bitwise operation docs

Nick Coghlan added the comment: I like Mark's phrasing as well. For precision, I'd still like to give an exact algorithmic formulation of what "large enough" means in this context, though. Something like: Each bitwise operation has the same result as though carried

[issue29710] Incorrect representation caveat on bitwise operation docs

Martin Panter added the comment: FWIW I find Mark’s suggestion pretty good: “Each bitwise operation has the same result as though carried out in two's complement using a bit-width that's large enough to represent the inputs.” --

[issue29710] Incorrect representation caveat on bitwise operation docs

Mark Dickinson added the comment: > “Bitwise operations have the same result as calculations using two’s > complement with a bit-width large enough to avoid overflows.” That sounds fine to me, but then, the original wording sounds fine to me now that I know how to read

[issue29710] Incorrect representation caveat on bitwise operation docs

Nick Coghlan 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

[issue29710] Incorrect representation caveat on bitwise operation docs

Martin Panter added the comment: I find the model in terms of “bit_length” hard to understand. You have to understand what bit_length returns, and why you added 1. Bit_length is awkward for negative numbers. It only uses the absolute value, which would give off-by-one

[issue29710] Incorrect representation caveat on bitwise operation docs

Mark Dickinson added the comment: Adding Tim Peters to the nosy, since I suspect (without actually having checked) that this is his language. -- nosy: +tim.peters ___ Python tracker

[issue29710] Incorrect representation caveat on bitwise operation docs

Mark Dickinson added the comment: So on re-reading the docs, I think we're misinterpreting this part: > this assumes that there are enough bits so that no overflow occurs during the > operation One way to think of | and & (and ~ and ^, too): 1. Find a positive integer n such that both x and

[issue29710] Incorrect representation caveat on bitwise operation docs

Changes by Sanyam Khurana : -- pull_requests: +1784 ___ Python tracker ___ ___

[issue29710] Incorrect representation caveat on bitwise operation docs

Nick Coghlan added the comment: I think the simplest fix to make the docs "not wrong" would be to just delete the part in parentheses. Beyond that, I'm not quite sure how to concisely describe the actual behaviour, but I think the mention of "2's complement" isn't especially helpful in its

[issue29710] Incorrect representation caveat on bitwise operation docs

Nick Coghlan added the comment: Added 2.7 to the list of affected versions. Clearly my 2's-complement arithmetic is incredibly rusty, as for some reason I was thinking "~(-sys.maxint-1)" could overflow, but no, the answer to that is just "sys.maxint" :) -- versions: +Python 2.7

[issue29710] Incorrect representation caveat on bitwise operation docs

Mark Dickinson added the comment: > It's not really clear what that line in the docs means for Python 2, either Ah, I guess it still kinda sorta applies for the left-shift operator, though even then, Python has promoted the result to long for many versions now. So the only "overflow" that's

[issue29710] Incorrect representation caveat on bitwise operation docs

Mark Dickinson added the comment: > This sentence isn't correct now that integers are always arbitrary length. It's not really clear what that line in the docs means for Python 2, either: if values x and y both fit in an int, then so do ~x, x|y and x We already assume in the Python source

[issue29710] Incorrect representation caveat on bitwise operation docs

Changes by Wolfgang Maier : -- nosy: +wolma ___ Python tracker ___

[issue29710] Incorrect representation caveat on bitwise operation docs

Sanyam Khurana added the comment: Hi, I'm working on this issue. -- nosy: +CuriousLearner ___ Python tracker ___

[issue29710] Incorrect representation caveat on bitwise operation docs

New submission from Nick Coghlan: The docs on bitwise operations at https://docs.python.org/3/library/stdtypes.html#bitwise-operations-on-integer-types include the caveated sentence: Negative numbers are treated as their 2’s complement value (this assumes that there are enough bits so