gh-115937: Remove implementation details from inspect.signature() docs

[erlend-aasland]

Co-authored-by: Carol Willing carolcode@willingconsulting.com
Co-authored-by: Gregory P. Smith greg@krypto.org
Co-authored-by: Jelle Zijlstra jelle.zijlstra@gmail.com

• Issue: Incorrect description of the __signature__ attribute in docs #115937

---

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

[Gouvernathor]

I disapprove of this way of solving the issue. @ethanfurman did not explain the rationale for changing the inspect module this way for the sole benefit of enum where it would have been just as easy not to (as #115984 shows).

The use of __signature__ as a cache - or as a lie to hide undocumented parameters - is too useful a feature to be undocumented.

[gpshead]

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.

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.

[willingc]

@erlend-aasland I think this documentation change with the implementation detail directive accurately reflects the current status of the underlying source code.

[willingc]

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.

@Gouvernathor As @gpshead mentions, I think having a separate (from documentation) discussion about behavior as a public API makes good sense. Also, I see you maintain ren'py, thanks for doing so. For years, my daughter used it to create interactive game scenarios (she is now a game developer).

[skirpichev]

Should I close #115984 in favor of this approach?

[erlend-aasland]

Should I close #115984 in favor of this approach?

Yes, please.

[erlend-aasland]

Thanks for the reviews!

[bedevere-app]

GH-116106 is a backport of this pull request to the 3.12 branch.

[bedevere-app]

GH-116107 is a backport of this pull request to the 3.11 branch.

[Gouvernathor]

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

Following this, I think I will open a non-doc issue about reverting what #100039 changed about signatures.

But aside from that, and contrary to my first impression, that Enum PR didn't actually introduce an incompatible change. The __signature__ field accepted a Signature|None object since around 2014 (raising a TypeError for other types) and now accepts Signature|str|Callable[[], Signature]|None which is wider.
While I believe both of these additions are a bad design choice for reasons I explained in the linked issue, I think it would still be good to document that passing a Signature object makes it be returned by inspect.signature, that it's not an implementation detail (contrary to how this pull request presents it), and that any other value aside from None is undocumented and implementation-detail territory.
Such a formulation would keep the cachie/lie behavior I defended above and introduced in the original PEP to remain a documented feature.
I'm not sure how people intervening in this merge request would stand about these two propositions, so I would like feedback on that.

---

Also, I see you maintain ren'py, thanks for doing so.

You're very welcome. All the best to your daughter.