bpo-24234: implement complex.__complex__

[mdickinson]

This PR implements the __complex__ method for the complex type. This slightly simplifies the check for whether a Python object can be used as a complex number, and means that that check can be implemented purely in terms of the existence of special methods - an object x can be used as a complex number if its type implements at least one of __index__, __float__ or __complex__.

https://bugs.python.org/issue24234

[mdickinson]

Hmm; there's an annoying test_doctest failure:

**********************************************************************
File "/Users/runner/work/cpython/cpython/Lib/test/test_doctest.py", line 671, in test.test_doctest.test_DocTestFinder.non_Python_modules
Failed example:
    816 < len(tests) < 836 # approximate number of objects with docstrings
Expected:
    True
Got:
    False

Given that there have probably been other docstrings added to builtins since this was last touched (e.g., int.bitcount), and that the failures appear to be the result of hitting the upper end of the (816, 836) range, I've bumped the expected numbers up to 820 < len(tests) < 840. But this feels like a rather awkward and fragile test.

[corona10]

@mdickinson
I would like to suggest adding test in test_typing.py

--- a/Lib/test/test_typing.py
+++ b/Lib/test/test_typing.py
@@ -1540,6 +1540,7 @@ def __complex__(self):

         self.assertIsSubclass(C, typing.SupportsComplex)
         self.assertNotIsSubclass(str, typing.SupportsComplex)
+        self.assertIsSubclass(complex, typing.SupportsComplex)

[mdickinson]

I would like to suggest adding test in test_typing.py

Thanks! Done.

[corona10]

(.oss) ➜  cpython git:(pr/27887) ✗ ./python.exe -m test test_typing.py test_comp
lex -R 3:3
0:00:00 load avg: 3.41 Run tests sequentially
0:00:00 load avg: 3.41 [1/2] test_typing
beginning 6 repetitions
123456
......
0:00:02 load avg: 3.41 [2/2] test_complex
beginning 6 repetitions
123456
......

== Tests result: SUCCESS ==

All 2 tests OK.

Total duration: 5.6 sec
Tests result: SUCCESS

LGTM, no leak was found.

[gvanrossum]

Thanks!