Author rhettinger
Recipients Dennis Sweeney, docs@python, eyadams, mark.dickinson, rhettinger, steven.daprano
Date 2021-09-09.17:22:40
SpamBayes Score -1.0
Marked as misclassified Yes
Message-id <1631208160.91.0.39538355155.issue44344@roundup.psfhosted.org>
In-reply-to
Content
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).
History
Date User Action Args
2021-09-09 17:22:40rhettingersetrecipients: + rhettinger, mark.dickinson, steven.daprano, docs@python, Dennis Sweeney, eyadams
2021-09-09 17:22:40rhettingersetmessageid: <1631208160.91.0.39538355155.issue44344@roundup.psfhosted.org>
2021-09-09 17:22:40rhettingerlinkissue44344 messages
2021-09-09 17:22:40rhettingercreate