Currently, the second paragraph ofdocs starts with "The arguments must have numeric types." That seems to be too restrictive and many third-party packages already break this rule. E.g. SymPy support arbitrary symbolic expressions:

In [1]: pow(x, y)Out[1]:  yx In [2]: pow(x, y, z)Out[2]:  y      x  mod z

Diofant also uses both forms for polynomial arithmetic:

In [1]: R, x = ring('x', QQ)In [2]: pow(x + 1, 7, 2*x**2 - 1)Out[2]: 239/8*x + 169/8In [3]: ((x + 1)**7) % (2*x**2 - 1)Out[3]: 239/8*x + 169/8In [4]: (x + 1)**2Out[4]: x**2 + 2*x + 1In [5]: pow(x + 1, 2)Out[5]: x**2 + 2*x + 1

I suggest to drop this requirement. In fact, first paragraph already mention equivalents for two-arg and three-arg versions of the pow(). We can rephrase it like this: "Return base to the power exp, an equivalent tobase**exp; if mod is present, return base to the power exp, modulo mod, an equivalent to(base**exp) % mod (but computed more efficiently)."

The third paragraph also might instead specify requirements for the mod in case ofinteger base and exponent, not just for builtin int's.