Message401500
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). |
|
Date |
User |
Action |
Args |
2021-09-09 17:22:40 | rhettinger | set | recipients:
+ rhettinger, mark.dickinson, steven.daprano, docs@python, Dennis Sweeney, eyadams |
2021-09-09 17:22:40 | rhettinger | set | messageid: <1631208160.91.0.39538355155.issue44344@roundup.psfhosted.org> |
2021-09-09 17:22:40 | rhettinger | link | issue44344 messages |
2021-09-09 17:22:40 | rhettinger | create | |
|