gh-108901: Add bound_arg to Signature.from_callable() and signature()

[sobolevn]

• Issue: Add modern alternatives to inspect module, deprecate old incorrect APIs #108901

---

📚 Documentation preview 📚: https://cpython-previews--116559.org.readthedocs.build/

[vstinner]

By the way, skip_bound_arg parameter name is a little bit long. Maybe you can rename it to bound_arg.

@pitrou: Do you have an opinion on the parameter name? :-)

[sobolevn]

I would prefer to have skip_bound_arg as a name, because it has a history (from existing code in inspect.py):

cpython/Lib/inspect.py

Lines 1404 to 1413 in 4e5df20

	# Re: `skip_bound_arg=False`
	#
	# There is a notable difference in behaviour between getfullargspec
	# and Signature: the former always returns 'self' parameter for bound
	# methods, whereas the Signature always shows the actual calling
	# signature of the passed object.
	#
	# To simulate this behaviour, we "unbind" bound methods, to trick
	# inspect.signature to always return their first parameter ("self",
	# usually)

[vstinner]

skip_bound_arg=False is a double negation, and I'm always confused by double negation :-( bound_arg=True is more straightfoward to me.

Previously, the argument was private, no?

[sobolevn]

Yes, it was private. It only existed on protected _signature_from_callable helper.

[sobolevn]

Done, now it is named bound_arg! 👍

[encukou]

What's the motivation for this change? I can't find the discussion behind it.

My worry is that it only works on some callables, and it's not very clear which ones those are -- or how to make a custom callable (e.g. one implemented in the C API) work like a method.

[sobolevn]

What's the motivation for this change?

I want to deprecate getfullargspec, which works almost like signature(), but with this difference. See

cpython/Lib/inspect.py

Lines 1403 to 1423 in 2c45148

	# Re: `skip_bound_arg=False`
	#
	# There is a notable difference in behaviour between getfullargspec
	# and Signature: the former always returns 'self' parameter for bound
	# methods, whereas the Signature always shows the actual calling
	# signature of the passed object.
	#
	# To simulate this behaviour, we "unbind" bound methods, to trick
	# inspect.signature to always return their first parameter ("self",
	# usually)
	# Re: `follow_wrapper_chains=False`
	#
	# getfullargspec() historically ignored __wrapped__ attributes,
	# so we ensure that remains the case in 3.3+
	sig = _signature_from_callable(func,
	follow_wrapper_chains=False,
	skip_bound_arg=False,
	sigcls=Signature,
	eval_str=False)

My worry is that it only works on some callables, and it's not very clear which ones those are -- or how to make a custom callable (e.g. one implemented in the C API) work like a method.

It will work exactly like this older function.

[encukou]

Is this behaviour useful, or is it a bug that's kept in getfullargspec for backwards compatibility?

[ncoghlan]

It's better to describe the non-default behaviour for boolean options (so folks know what they'll get if they request non-default behaviour):

Suggested change

	If *bound_arg* is ``False``, remove ``self`` parameter
	from the method signature.
	If *bound_arg* is ``True``, report the (already bound) first parameter on bound
	instance or class methods (usually ``self`` or ``cls``). This emulates the historical
	behaviour of the deprecated :func:`getfullargspec` function.

(Describing both behaviours is also an option, but it seemed excessively verbose in this case)

[ncoghlan]

Reword here to match the updated main function docs (including mentioning the getfullargspec compatibility)

[ncoghlan]

Maybe make the backport mention a seealso note in the module docs rather than only putting it here?

[ncoghlan]

Mention the getfullargspec compatibility aspect here.

[vstinner]

Is this behaviour useful, or is it a bug that's kept in getfullargspec for backwards compatibility?

IMO it's useful in general, not only for backward compatibility. Keep self or not should be configurable.

[ncoghlan]

Is this behaviour useful, or is it a bug that's kept in getfullargspec for backwards compatibility?

I think it was primarily a quirk of the way getfullargspec was originally implemented (i.e. it followed bound methods down to the underlying function to get the signature details, and then just returned those details as is without accounting for the first parameter already being bound).

However, the suggested flag isn't hard to maintain, since the complexity is in the branch that corrects the underlying function signature to remove the already bound first parameter (the default behaviour). The "unwrap bound methods" branch is literally just return sig:

cpython/Lib/inspect.py

Line 2517 in 3989894

if skip_bound_arg:

I do think making the flag public is worth including as a step prior to full programmatic deprecation of getfullargspec. With the suggested docs change, I also think the bound_arg parameter name is a reasonable one.

(The one potential argument I see for a parameter name like unbind_methods over bound_arg, is that the flag specifically affects the handling of the bound arg in bound methods. It doesn't have any effect on the handling of the previously bound arguments in functools.partial and functools.partialmethod instances. However, I don't think that concern is significant enough to be worth changing the parameter name again)

[encukou]

the suggested flag isn't hard to maintain

My worry is that while the flag isn't hard to maintain as an internal detail of how getfullargspec extracts information from Python functions/methods, signature should work for other callables, like instances of C extension types (e.g. ones with Py_TPFLAGS_METHOD_DESCRIPTOR), or Cython functions. We might not be able to support these things transparently, but there should be a clear way to make custom objects that work with the flag. Or a documented way, at least.

(Unfortunately I'll probably not have time to investigate this worry before beta 1. If the feature is waiting for my review, it won't make it.)