Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Re-document __signature__ as a feature #116124

Closed
wants to merge 1 commit into from

Conversation

Gouvernathor
Copy link
Contributor

@Gouvernathor Gouvernathor commented Feb 29, 2024

This seeks to re-resolve #106310, and improve #116086 in resolving #115937.

The original pull request for #106310, #106311, documented the behavior as the original PEP362 described it : any object found in __signature__ and not None would be returned by inspect.signature. But in fact, since 2014 apparently, a type guard allowing only instances of Signature to pass, or else raise an exception. The documentation was in fact inaccurate as a result.

Other changes to the inspect.signature function occurred through #100039 where it gained implementation-detail support for strings and callables to be set as __signature__, something which I'm trying to roll back. Regardless, the latest change to the documentation which sought to address the discrepancies between the doc and the implementation, #115937, demoted the Signature-in-__signature__ behavior from a feature to a vague implementation detail.

My proposition is to document things the following way:

  • Signature objects in __signature__ are returned as-is by the inspect.signature function
  • None is ignored and the behavior is as if __signature__ was not set
  • Behavior for any other value is an implementation detail.

That way, uses of __signature__ as a cache or as a way to hide undocumented parameters remains guaranteed, while allowing the strings and callables support to be decided and to evolve separately.

I kept the "consult the source code for current semantics" line in an effort to limit changes to a minimum, but I would be in favor of removing it.


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

@erlend-aasland
Copy link
Contributor

#116086 was written by four core devs. I think that is a strong indication on we want these docs to be formulated.

@Gouvernathor
Copy link
Contributor Author

Gouvernathor commented Feb 29, 2024

@erlend-aasland
As written in that PR's discussion, @gpshead (a core dev I believe) said :

I do understand the Python user desire for officially describing and documenting signature behavior as a public API people can rely on. That's outside the scope of this specific issue as this doc update is just trying to set expectations anywhere the existing implementation detail is mentioned.

They also incidentally criticize the "consult the source code for current semantics" line, as I do.
@willingc (also a core dev) thinks

having a separate (from documentation) discussion about behavior as a public API makes good sense.

When and where, if not here, should that discussion happen ?

@erlend-aasland
Copy link
Contributor

When and where, if not here, should that discussion happen ?

I think the Documentation category on Discourse is a good fit:

They also incidentally criticize the "consult the source code for current semantics" line, as I do.

I think that's not a fair description of @gpshead's comment. Let me C&P it here1:

I'd leave the "Consult the source code for current semantics." bit off as that feels implied to be when calling something "an implementation detail". But no big deal either way as it is true.

Footnotes

  1. emphasis, mine

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
awaiting review docs Documentation in the Doc dir skip news
Projects
None yet
Development

Successfully merging this pull request may close these issues.

__signature__ in the inspect module
2 participants