[skirpichev]

• Issue: Documented parameter names of some inspect functions don't match the implementation #161591

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #35731918 | 📁 Comparing 06c7183 against main (f767423)

  🔍 Preview build  

2 files changed

± library/inspect.html
± whatsnew/changelog.html

[skirpichev]

I prefer sphinx's version of the argument name. But renaming would introduce API break (though hardly it's severe), not sure if it worth.

Kept changes minimal, per issue description. But in fact many singnatures in the inspect module are out of sync with the real code and/or just invalid. Examples:

.. function:: getmembers(object[, predicate])
   [...]
.. function:: getmembers_static(object[, predicate])
   [...]

I would prefer to fix all in one shot, in this pr, if reviewers support this.

CC @sobolevn

[picnixz]

I suggest you fix the docs properly even if naming is a bit.. wrong

[skirpichev]

Ok, lets use obj...

But what about other signatures? Mentioned above could be fixed easily. Should I do it in this pr? Another one, formatargvalues() - probably must wait a better repr() for lambda, see #79037.

[picnixz]

Mmh. Now that you say it, the docs are more meaningful. Here's what I suggest:

• in this PR, align the docs with actual signature
• in a follow-up, let's decide whether to break the signatures or not; I would be favorable to. We can have a deprecation period where first arguments become deprecated when passed as keyword arguments. I made a similar change for hashlib where parameter string/data were used across multiple hash functions and I deprecated the 'string' parameter.

An alternative is to mark the first parmaeter as positional-only in the docs. It's a lie but... it would also hide the fact that it's an implementation detail and will forbid users to use named params.

[skirpichev]

in this PR, align the docs with actual signature

Ok, lets keep this as is.

in a follow-up, let's decide whether to break the signatures or not; I would be favorable to. We can have a deprecation period where first arguments become deprecated when passed as keyword arguments.

You meant:

1. deprecate obj as positional or keyword
2. make it positional-only, rename
3. then allow it as keyword.

Sure, we can introduce breaking change that way, but IMO it's overkill. Hardly someone now uses signature(obj=foo) form versus positional argument.

An alternative is to mark the first parameter as positional-only in the docs.

Then next time someone else will point to inconsistency between docs and actual API.

[picnixz]

Ok, so let's do the doc update first. That is, sync every signature with existing code first. And in a follow-up, I suggest we just break the signatures (but for that we need an issue and maybe someone else that would be ok with that)

[picnixz]

Btw, which signature is typeshed using?