Expose meaningful keyword arguments for pow()

[rhettinger]

BPO	38237
Nosy	@rhettinger, @mdickinson, @ambv, @serhiy-storchaka, @ammaraskar, @pablogsal, @miss-islington, @lschoe
PRs	bpo-38237: Make pow's arguments have more descriptive names and be keyword passable #16302 [3.8] bpo-38237: Make pow's arguments have more descriptive names and be keyword passable (GH-16302) #16320 [3.8] bpo-38237: Shorter docstring (GH-16322) #16323 bpo-38237: Fix "versionchanged" for pow named arguments #19042 [3.8] bpo-38237: Fix "versionchanged" for pow named arguments (GH-19042) #19079 bpo-38237: Use divmod for positional arguments whatsnew example #19171 [3.8] bpo-38237: Use divmod for positional arguments whatsnew example (GH-19171) #19192

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/rhettinger'
closed_at = <Date 2019-09-21.16:50:01.178>
created_at = <Date 2019-09-20.17:21:42.262>
labels = ['easy', '3.8', 'type-feature', 'library', '3.9']
title = 'Expose meaningful keyword arguments for pow()'
updated_at = <Date 2020-03-27.16:45:09.009>
user = 'https://github.com/rhettinger'

bugs.python.org fields:

activity = <Date 2020-03-27.16:45:09.009>
actor = 'miss-islington'
assignee = 'rhettinger'
closed = True
closed_date = <Date 2019-09-21.16:50:01.178>
closer = 'rhettinger'
components = ['Library (Lib)']
creation = <Date 2019-09-20.17:21:42.262>
creator = 'rhettinger'
dependencies = []
files = []
hgrepos = []
issue_num = 38237
keywords = ['patch', 'easy (C)']
message_count = 28.0
messages = ['352876', '352877', '352878', '352879', '352880', '352881', '352885', '352886', '352887', '352895', '352900', '352923', '352924', '352927', '352933', '352939', '352944', '352951', '352952', '364395', '364396', '364397', '364400', '364401', '364402', '364414', '365166', '365167']
nosy_count = 8.0
nosy_names = ['rhettinger', 'mark.dickinson', 'lukasz.langa', 'serhiy.storchaka', 'ammar2', 'pablogsal', 'miss-islington', 'lschoe']
pr_nums = ['16302', '16320', '16323', '19042', '19079', '19171', '19192']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue38237'
versions = ['Python 3.8', 'Python 3.9']

[rhettinger]

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)

[ammaraskar]

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?

[ammaraskar]

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

[ammaraskar]

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

[serhiy-storchaka]

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.

[ammaraskar]

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

[mdickinson]

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.

[serhiy-storchaka]

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

[serhiy-storchaka]

And pow(2.0, 3.0) please.

[ammaraskar]

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

[ammaraskar]

math.pow changes removed from PR