Raymond Hettinger <raymond.hettin...@gmail.com> added the comment:
The pow() docs could use substantial updating. All of the logic for pow() is implemented in base.__pow__(exp, [mod]). Technically, it isn't restricted to numeric types, that is just a norm. The relationship between "pow(a,b)" and "a**b" is that both make the same call, a.__pow__(b). The discussion of coercion rules dates back to Python 2 where used to have a coerce() builtin. Now, the cross-type logic is buried in either in type(a).__pow__ or in type(b).__rpow__. The equivalence of pow(a, b, c) to a more efficient form of "a ** b % c" is a norm but not a requirement and is only supported by ints or third-party types. My suggestions 1st paragraphs: Stay at a high level, covering only the most common use case and simple understanding of how most people use pow(): Return *base* to the power *exp* giving the same result as ``base**exp``. If *mod* is present and all the arguments are integers, return *base* to the power *exp*, modulo *mod*. This gives the same result as ``base ** exp % mod`` but is computed much more efficiently. 2nd paragraph: Be precise about what pow() actually does, differentiating the typical case from what is actually required: The :func:`pow` function calls the base's meth:`__pow__` method falling back to the exp's meth:`__rpow__` if needed. The logic and semantics of those methods varies depending on the type. Typically, the arguments have numeric types but this is not required. For types that support the three-argument form, the usual semantics are that ``pow(b, e, m)`` is equivalent to ``a ** b % c`` but this is not required. 3rd paragraph: Cover behaviors common to int, float, and complex. 4th paragraph and later: Cover type specific behaviors (i.e. only int supports the three argument form and the other arguments must be ints as well). ---------- nosy: +rhettinger _______________________________________ Python tracker <rep...@bugs.python.org> <https://bugs.python.org/issue44344> _______________________________________ _______________________________________________ Python-bugs-list mailing list Unsubscribe: https://mail.python.org/mailman/options/python-bugs-list/archive%40mail-archive.com
