Issue 38237: Expose meaningful keyword arguments for pow()

Current signature:

    pow(x, y, z=None, /)


Proposed signature:

    pow(base, exp, mod=None)


Benefits:

* Meaningful and self-explanatory parameters in tooltips

* Optionally clearer calls for the three argument form:

     pow(2, 5, mod=4)

* More usable with partial():

     squared = partial(pow, exp=2)

Looks like a solid proposal, I especially like the clarity for the 3-argument call. Often beginners ask about why there's a third argument in pow especially when teaching RSA and number-theoretic stuff.

Do you mind if I take this on Raymond?

Actually quick question, should a similar change be made for `math.pow` for consistency's sake?

I've made a PR, feel free to close it if you'd rather implement this yourself or this proposal won't be accepted :)

You can use a lambda instead of partial:

    squared = lambda x: pow(x, 2)

Proposed names look meaningful. But after adding support of keyword arguments please compare performance of the old and the new functions. I expect that the difference will be small, but we need to check.

Here's a little microbenchmark, let me know if there's anything specific you'd like to see:

Before
======

> python -m pyperf timeit "from test.test_builtin import BuiltinTest; tst = BuiltinTest()" -- "tst.test_pow()"

Mean +- std dev: 3.80 us +- 0.23 us

> python -m pyperf timeit "pow(23, 19, 3)"

Mean +- std dev: 519 ns +- 12 ns


After
=====

> python -m pyperf timeit "from test.test_builtin import BuiltinTest; tst = BuiltinTest()" -- "tst.test_pow()"

Mean +- std dev: 3.80 us +- 0.26 us

> python -m pyperf timeit "pow(23, 19, 3)"

Mean +- std dev: 526 ns +- 18 ns

The proposal sounds reasonable to me.

> should a similar change be made for `math.pow` for consistency's sake?

I'd leave math.pow alone here.

Thank you. Could you please test simpler examples like pow(2, 3)? Please use the --duplicate option.

And pow(2.0, 3.0) please.

Before
======

>python -m pyperf timeit "pow(2, 3)" --duplicate 100000
Mean +- std dev: 242 ns +- 19 ns

> python -m pyperf timeit "pow(2.0, 3.0)" --duplicate 100000
Mean +- std dev: 197 ns +- 16 ns

After
=====

> python -m pyperf timeit "pow(2, 3)" --duplicate 100000
Mean +- std dev: 243 ns +- 11 ns

> python -m pyperf timeit "pow(2.0, 3.0)" --duplicate 100000
Mean +- std dev: 200 ns +- 14 ns

math.pow changes removed from PR

New changeset 87d6cd3604e5c83c06339276228139f5e040b0e7 by Miss Islington (bot) (Ammar Askar) in branch 'master':
bpo-38237: Make pow's arguments have more descriptive names and be keyword passable (GH-16302)
https://github.com/python/cpython/commit/87d6cd3604e5c83c06339276228139f5e040b0e7

Thanks Ammar

Thank you for your contribution Ammar! Nice work!

New changeset 37bc93552375cb1bc616927b5c1905bae3c0e99d by Raymond Hettinger (Miss Islington (bot)) in branch '3.8':
bpo-38237: Let pow() support keyword arguments (GH-16302) (GH-16320)
https://github.com/python/cpython/commit/37bc93552375cb1bc616927b5c1905bae3c0e99d

Isn't it a new feature? Isn't it too later to add it to 3.8?

As noted in the checkin, this was backported with the release manager's assent.

FWIW, pow() itself is an old feature, recently enhanced to support negative powers in a given modulus.  When the enhancement went in, we should have done this as well.

New changeset 24231ca75c721c8167a7394deb300727ccdcba51 by Raymond Hettinger (Miss Islington (bot)) in branch '3.8':
bpo-38237: Shorter docstring (GH-16322) (GH-16323)
https://github.com/python/cpython/commit/24231ca75c721c8167a7394deb300727ccdcba51

Thank you for the explanation Raymond and sorry for the disturb. My mistake, I had not noticed the release manager's assent.

There seems to be a slight mixup with the built-in pow() function in Python 3.8.2.

Currently, under https://docs.python.org/3/library/functions.html#pow it says:

	Changed in version 3.9: Allow keyword arguments. Formerly, only positional arguments were supported.
	
I think this should be into "Changed in version 3.8 ... ", as pow(3,4, mod=5) actually works in Python 3.8.2.

The "What’s New In Python 3.8" also needs to be changed accordingly. 
In https://docs.python.org/3/whatsnew/3.8.html#positional-only-parameters it says:

	One use case for this notation is that it allows pure Python functions to fully emulate behaviors of existing C coded functions. For example, the built-in pow() function does not accept keyword arguments:
		def pow(x, y, z=None, /):
			"Emulate the built in pow() function"
			r = x ** y
			return r if z is None else r%z
			
This example can simply be dropped now.

> This example can simply be dropped now.

It could be, but it would be better to replace it with a different example that works. Any suggestions?

In my original PR I changed it to divmod: https://github.com/python/cpython/pull/16302/files#diff-986275b975a33c44c0aba973362516fa

It is hard to find a builtin which could be easy and clearly implemented in Python (it means no use of dunder methods). Maybe sorted()?

def sorted(iterable, /, *, key=None, reverse=False):
    """Emulate the built in sorted() function"""
    result = list(iterable)
    result.sort(key=key, reverse=reverse)
    return result

Although I think that this use case is less important. The primary goal of the feature is mentioned at the end of the section -- easy way to implement functions which accept arbitrary keyword arguments.

divmod() should be implemented via __divmod__ and __rdivmod__. And they should be looked up on the type, not instance. There is no easy way to express it in Python accurately. This would make the example too complex.

I don't think that matters. The example is supposed to just serve as an illustration, it doesn't need to encode the dunder dispatch semantics. The already existing example doesn't check for a __pow__.

I'd picture it just as:

return x//y, x%y

Maybe a use case in this direction: int(x, base=10).
Because, if you type 

    int(x='3', base=12)

you get

    TypeError: 'x' is an invalid keyword argument for int()

and x needs to be a positional-only to program this yourself.

New changeset 5a58c5280b8df4ca5d6a19892b24fff96e9ea868 by Ammar Askar in branch 'master':
bpo-38237: Use divmod for positional arguments whatsnew example (GH-19171)
https://github.com/python/cpython/commit/5a58c5280b8df4ca5d6a19892b24fff96e9ea868

New changeset 9c5c497ac167b843089553f6f62437d263382e97 by Miss Islington (bot) in branch '3.8':
bpo-38237: Use divmod for positional arguments whatsnew example (GH-19171)
https://github.com/python/cpython/commit/9c5c497ac167b843089553f6f62437d263382e97

messages: + msg352944
versions: + Python 3.8

stage: patch review -> resolved