gh-64373: Convert _functools to Argument Clinic

[sobolevn]

A couple of extra notes:

• functools.reduce is not converted, because its args parsing / in-place mutation is optimized
• partial_new and partial_call require *args, **kwargs, as far as I know AC does not support that at the moment, they are not converted
• The same for _lru_cache_wrapper.__call__
• I've also noticed a couple of other oddities that I will report in two separate issue later

• Issue: Derby #5: Convert 50 sites to Argument Clinic across 3 files #64373

[sobolevn]

Now, let's compare help() before and after!

cmp_to_key

Before:

>>>help(_functools.cmp_to_key)
Helponbuilt-infunctioncmp_to_keyinmodule_functools:
cmp_to_key(...)
Convertacmp=functionintoakey=function.

After:

>>>help(_functools.cmp_to_key)
Helponbuilt-infunctioncmp_to_keyinmodule_functools:
cmp_to_key(mycmp)
Convertacmp=functionintoakey=function.
mycmpFunctionthatcomparestwoobjects.

_lru_cache_wrapper

Before:

>>>help(_functools._lru_cache_wrapper)
Helponclass_lru_cache_wrapperinmodulefunctools:
class_lru_cache_wrapper(builtins.object)
|Createacachedcallablethatwrapsanotherfunction.
||user_function: thefunctionbeingcached||maxsize: 0fornocaching|Noneforunlimitedcachesize|nforaboundedcache||typed: Falsecachef(3) andf(3.0) asidenticalcalls|Truecachef(3) andf(3.0) asdistinctcalls||cache_info_type: namedtupleclasswiththefields:
|hitsmissescurrsizemaxsize||Methodsdefinedhere:

After:

>>>help(_functools._lru_cache_wrapper)
Helponclass_lru_cache_wrapperinmodulefunctools:
class_lru_cache_wrapper(builtins.object)
|_lru_cache_wrapper(user_function, maxsize, typed, cache_info_type)
||Createacachedcallablethatwrapsanotherfunction.
||user_function|thefunctionbeingcached|maxsize|0fornocaching|Noneforunlimitedcachesize|nforaboundedcache|typed|Falsecachef(3) andf(3.0) asidenticalcalls|Truecachef(3) andf(3.0) asdistinctcalls|cache_info_type|namedtupleclasswiththefields:
|hitsmissescurrsizemaxsize||Methodsdefinedhere:

.cache_clear and .cache_info

Before:

>>>help(_functools._lru_cache_wrapper.cache_clear)
Helponmethod_descriptor:
cache_clear(...)
>>>help(_functools._lru_cache_wrapper.cache_info)
Helponmethod_descriptor:
cache_info(...)

After:

>>>help(_functools._lru_cache_wrapper.cache_clear)
Helponmethod_descriptor:
cache_clear(self, /)
Clearthecacheandcachestatistics>>>help(_functools._lru_cache_wrapper.cache_info)
Helponmethod_descriptor:
cache_info(self, /)
Reportcachestatistics

[rhettinger]

We generally only apply argclinic to functions directly visible to the user. Otherwise, it is mostly pointless since no one sees the signature. So, I would leave the lru cache internals alone -- iirc, we had an issue for this previously. It was would be a lot of code churn for no benefit. The cmp_to_key() part can stay.

[sobolevn]

Thank you for the insight! This is my first clinic-related PR.

I will remove things like __copy__ and other internals tomorrow 👍

to functions directly visible to the user
I would leave the lru cache internals alone

I think that .clear_cache and .cache_info are user-facing functions, aren't they?

[rhettinger]

I think that .clear_cache and .cache_info are user-facing functions, aren't they?

You can change those two zero-argument methods if you want.

[bedevere-bot]

A Python core developer has requested some changes be made to your pull request before we can consider merging it. If you could please address their requests along with any other requests in other reviews from core developers that would be appreciated.

Once you have made the requested changes, please leave a comment on this pull request containing the phrase I have made the requested changes; please review again. I will then notify any core developers who have left a review that you're ready for them to take another look at this pull request.

[sobolevn]

I have made the requested changes; please review again

[bedevere-bot]

Thanks for making the requested changes!

@rhettinger: please review the changes made to this pull request.