gh-124153: Introduce PyType_GetBaseByToken function (PoC)

[neonene]

Reference implementation of the following C-API functinons:

• PyType_GetBaseByToken()
• PyType_GetToken()

Discussion: https://discuss.python.org/t/55598

---

📚 Documentation preview 📚: https://cpython-previews--121079.org.readthedocs.build/

• Issue: Add PyType_GetBaseByToken function with Py_tp_token slot #124153

[neonene]

The tp_bases can be used in a fallback implementation. I checked the overhead, adding a repeat function temporarily (100972d):

from timeit import timeit
setup = f"""if 1:
    import _testcapi
    A = _testcapi.create_type_with_token("_testcapi.A", 0)
    tokenA = _testcapi.get_tp_token(A)
    class B(A): pass
    class C(B): pass
    class D(C): pass
    class E(D): pass
    getbase = _testcapi.repeat_getbasebytoken
"""
c_repeat = 10  # py_repeat = timeit default (1000000)
mro   = timeit(s1 := f'getbase(C, tokenA, {c_repeat}, True)', setup)
bases = timeit(s2 := f'getbase(C, tokenA, {c_repeat}, False)', setup)
print(s1, mro)
print(s2, bases,  bases / mro)

Win non-debug: (the higher, the slower)

find A from	starts with	run once in C	repeat 10 in C
mro	class A	1.00	1.00
bases	class A	1.00x	1.00x
mro	class B	1.00x	1.05x
bases	class B	1.01x	1.14x
mro	class C	1.01x	1.10x
bases	class C	1.04x	1.40x
mro	class E	1.02x	1.16x
bases	class E	1.08x	1.50x

[encukou]

The code looks good. Do you want to clear the draft bit, and file an issue?

If there are performance more tweaks to make, they can go in a follow-up PR.

[encukou]

Could you remove the exercise from this PR?
Hopefully the training will get better as PyType_GetBaseByToken is used more; if not, we can adjust it in a future PR.

[neonene]

I'll post a new PR. It may be better to have a dedicated branch when the result argument is NULL.