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 87d6cd3 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)
87d6cd3

Thanks Ammar

Thank you for your contribution Ammar! Nice work!

New changeset 37bc935 by Raymond Hettinger (Miss Islington (bot)) in branch '3.8':
bpo-38237: Let pow() support keyword arguments (GH-16302) (GH-16320)
37bc935

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 24231ca by Raymond Hettinger (Miss Islington (bot)) in branch '3.8':
bpo-38237: Shorter docstring (GH-16322) (GH-16323)
24231ca

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 5a58c52 by Ammar Askar in branch 'master':
bpo-38237: Use divmod for positional arguments whatsnew example (GH-19171)
5a58c52

New changeset 9c5c497 by Miss Islington (bot) in branch '3.8':
bpo-38237: Use divmod for positional arguments whatsnew example (GH-19171)
9c5c497