The existing API for the builtin hash() function is inconvenient.  When implementing structure that use a hash value, you never want a negative number.  Running abs(hash(x)) works but is awkward, slower, and loses one bit of entropy.

The only problem is that the current algorithm for numeric types is documented to return negative numbers.
https://docs.python.org/3/library/stdtypes.html#hashing-of-numeric-types

We think can clarify that those docs describe int.__hash__, float.__hash__, and complex.__hash__.   

The builtin hash() function can and does make transformations on the result from the __dunder__ method:

    >>> class A:
	    def __hash__(self):
 		return 123423412341234123412341234

    >>> hash(A())
    1656462513496965462

This is a change of documented behaviour that will affect 3rd party libraries that provide numeric types, like NumPy and gmpy; it should not be done lightly. I think such a change deserves at least a deprecation warning, and should also be discussed more widely than just this issue.

Currently the hash for integers and several other types uses 62 bits of 64 (on 64-bit platform). The domain of values is continuous:

    -sys.hash_info.modulus < h < sys.hash_info.modulus

If interpret Py_hash_t as Py_uhash_t, it will no longer be continuous:

    0 <= h < sys.hash_info.modulus or 2**sys.hash_info.width-sys.hash_info.modulus < h < 2**sys.hash_info.width

The hash for tuples is written in term of signed hashes of elements. If write it in Python it will look more complicated for unsigned hashes.

What are problems with using negative hash values? In hash tables you squeeze it to valid range by evaluating `h % size` of `h & mask`. Both expressions give non-negative result.

Well, I have no code that would benefit from this change.  What's the point?  Sure, I use _parts_ of hash codes at times, but, e.g.,

    index = the_hash_code & SOME_LOW_BIT_MASK
    
in Python couldn't care less about the sign of `the_hash_code` - it returns a non-negative int regardless.  The same applies if, e.g., SOME_LOW_BIT_MASK is `(1 << sys.hash_info.hash_bits) - 1`, giving a full-width non-negative hash without losing a bit of "entropy".  But I've never felt a need for the latter.  Likewise for doing, e.g.,

    index = the_hash_code % SOME_POSITIVE_PRIME

in Python.  % takes the sign (positive here) of the modulus in Python.

So this _looks_ like pointlessly disruptive code churn to me.  What killer use case am I missing?

> What killer use case am I missing?

There's no killer use case. I just thought it weird that hte builtin hash() function ever returned a negative number.

> This is a change of documented behaviour that will affect 
> 3rd party libraries that provide numeric types, like NumPy
> and gmpy; it should not be done lightly.

Okay, I'm happy to drop this.  It was only a minor nuisance.

Am not sure at what point we ever guaranteed that hash() would return negative numbers, or any particular number.  That was probably a mistake.  I thought the guarantees were all higher level metamorphic invariants such as hash(x) == hash(y) when x == y and {type(x), type(y)} ⊂ {bool, int, float, Decimal, Fraction, complex}.

BTW, I'm not sure why the numeric hashes are not getting all 64 bits in to play:

    from random import randrange, expovariate
    from secrets import token_hex, token_bytes

    for random_hash in [
        lambda : hash(randrange(2**100)) % 2**64,
        lambda : abs(hash(expovariate(1.0))) % 2**64,
        lambda : hash(token_hex()) % 2**64,
        lambda : hash(token_bytes()) % 2**64,
    ]:
        print(max(random_hash().bit_length() for i in range(10_000)))

Outputs:

    61
    61
    64
    64

I agree:  we "shouldn't have" documented anything about hash codes beyond the invariants needed to guarantee they work for their intended purpose, chiefly that x == y implies hash(x) == hash(y).

Which leads to your other question ;-)  That invariant is tricky to maintain across a pile of distinct but comparable numeric types!  Whatever we return for an int needs also to be what's returned for a float that happens to have the same value, and whatever we return for a float needs also to be what's returned for a fraction.Fraction with the same value, and so on.

So Python uses a single numeric hashing algorithm defined on mathematical rationals, described here:

https://docs.python.org/3.8/library/stdtypes.html#hashing-of-numeric-types

Presumably that's documented so that people defining their own numeric types have a clue about how to implement compatible hash codes.

Anyway, that algorithm uses a large fixed prime P (different on 32- and 64-bit boxes), and uses operations modulo P.  That's why the full bit width isn't used.  And not just any prime P, it picks one for which computing the remainder mod P is especially efficient.  2**61 - 1 is as good as it gets on 64 bit boxes.

I didn't pick this algorithm (I suspect Mark did), but I certainly approve of it.  It's clever and general enough to apply to any plausible subset-of-real numeric type short of the constructive reals (where equality isn't even theoretically decidable, so "x == y implies ..." can't get off the ground ;-) ).

Withdrawing this issue and marking as closed.

Thanks for your thoughts on the subject.