Add partial stubs for fractions

[Michael0x2a]

This commit adds some incomplete stubs for the fractions module.

In particular, this pull request is basically a less complete version of #94 -- this pull request punts on adding type signatures to functions like __add__ and just sticks with annotating the more obvious functions and methods. This isn't ideal, but does allow us to move forward with creating stubs for the statistics module.

This pull request requires #545 to first be merged and accepted. (For some reason, the stubs for decimal in Python 3 are relatively complete, but the stubs for Python 2 are not, which is causing the current test failure).

However, this pull request can be reviewed and accepted independently from my other recent pull request that refines numbers.pyi. Once that other pull request is accepted, I'm planning on following up with another pull request that adds the __hash__ function to the Fractions class.

[gvanrossum]

Can you deal with the test failure? Seems your stubs are incompatible with Decimal.

[Michael0x2a]

Yeah -- the fix for that is here: #545

(Python 2's stubs for Decimals seem to be much less complete then Python 3's stubs, which is what's causing the incompatibility)

[gvanrossum]

I see. But the Python 2 stubs have to be compatible with the crummy production code we have at Dropbox using it. I think I have to make some changes there before that can land (or perhaps after).

[gvanrossum]

Now that the improved decimal stubs have landed can you rebase and re-push? to trigger the tests?

[Michael0x2a]

@gvanrossum -- done! It's green now :)

[gvanrossum]

I don't know what the docs say, but the module doesn't seem to support complex arguments here.

[gvanrossum]

At least not in Python 3. It does in Python 2?!

[Michael0x2a]

Hmm, so it looks like the return type of gcd here ultimately depends on what the type of a % b is, which makes the gcd function more complicated then I was originally expecting.

Some things I observed:

• numbers.Complex does not have any kind of dunder methods related to mods, so shouldn't be a legal input type in either Python 2 or Python 3.
• However, the builtins complex type does allow you to take the mod in Python 2, but NOT in Python 3.
• If one argument is a complex number, and the other is any other type, the gcd function will either throw a TypeError or will enter an infinite loop (!!).

I also found the full matrix of allowable parameters to return types is this (not taking into account whatever any custom number subclasses might do):

            | int          float        Fraction     Decimal      complex
------------+ -----------  -----------  -----------  -----------  -----------
int         | int          float        Fraction     Decimal      Inf. Loop
float       | float        float        float        TypeError    Inf. Loop
Fraction    | Fraction     float        Fraction     TypeError    TypeError
Decimal     | Decimal      TypeError    TypeError    Decimal      TypeError
complex     | Inf. Loop    Inf. Loop    TypeError    TypeError    complex

Thankfully, the diagonal (where both parameters are the same type) appear to be relatively sane.

So, given all of the above, and given that fractions.gcd is a deprecated function anyways as of Python 3 (people are supposed to use math.gcd instead, which accepts only ints), would you rather I:

• Attempt to come up with a system of overloads to handle the full matrix.
• Attempt to handle the case where both parameters are the same type, and just provide separate annotations for Python 2 and 3 to handle complex numbers.
• Just disallow allowing complex numbers as parameters completely on the grounds that nobody is actually going to do that/they're going to be using cmath instead.
• Don't bother providing a type signature, and just make the input and output types Any.
• Something else?

[gvanrossum]

Wow, you're reasoning like pytype. :-)

In 3.5, fractions.gcd() is deprecated in favor of math.gcd(), which only supports integers. I propose to make the type signature do that in all versions. Even the 2.7 docs say "integers"...

[Michael0x2a]

Hmm, ok -- I can do that.

I guess the only thing I'm hesitant about is that the source code of fractions.gcd explicitly handles the case where neither parameters are ints, which actually makes it bit more general-purpose then math.gcd.

But it seems like we're not really going to care about that?

[Michael0x2a]

Or actually, maybe make it just accept either int or numbers.Integral?

[gvanrossum]

Looking at the C source for math.gcd() it seems that supports things with
an index method, which is a proxy for being a sort of integer. So I
think Union[int, Integral] is fine!