GeezerVison

Documentation build overview

📚 cpython-previews | 🛠️ Build #35747967 | 📁 Comparing 329b466 against main (f767423)

  🔍 Preview build  

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

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

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.

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.

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)

Btw, which signature is typeshed using?

Ok, so let's do the doc update first.

Done.

1. formatargvalues() kept intact, as noted above
2. getmodule() has private parameter, _filename: not added to sphinx docs, like we have for the Fraction constructor. IMO, signature() should have some option to omit private arguments per default.
3. Signature constructor also has __validate_parameters__, probably it's private as well.
4. getcallargs() has different names for vararg/kwarg parameters: kept intact as there is not API difference.
5. getattr_static() uses old-style sentinel for default

Btw, which signature is typeshed using?

obj. It looks, they follow to sources.