gh-101552: Allow pydoc to display signatures in source format

[JelleZijlstra]

• Add a annotations_format argument to inspect.signature, matching annotationlib.Format
• Add an unquote_annotations argument to inspect.Signature.format, allowing string annotations to be displayed without quotes
• Use the new functionality in pydoc to display signatures in source format.

• Issue: The builtin help(...) should unstringify (and "unforwardref") annotations #101552

---

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

[carljm]

🐷

[AlexWaygood]

Nice! Some nitpicks, but nothing blocking really

[AlexWaygood]

This doesn't feel like a totally correct use of "unquote" to me... Maybe the parameter could be called remove_annotation_quotes instead of unquote_annotation...? I think that might also reflect slightly better the fact that not all annotations will necessarily be quoted at all.

[JelleZijlstra]

We use "unquote" in various other places (e.g., https://docs.python.org/3.13/library/csv.html#csv.QUOTE_NOTNULL); I feel it's more clear and concise

[AlexWaygood]

"unquoted" is used in https://docs.python.org/3.13/library/csv.html#csv.QUOTE_NOTNULL as an adjective rather than a verb. I think it makes sense to talk about something being "unquoted" but less sense to talk about "unquoting" something.

[larryhastings]

"dequote"?

[larryhastings]

If I'm reading the code correctly, if this is false (the default) we use repr on annotation values that are strings, and if it's true we skip repr only for strings. So this is a passive operation--if the value is true, we don't do something, and when it's false we do do something. I think that's why this is awkward.

I suggest the clearest way to express this is to flip it. Negate the boolean and rename it quote_annotations=True. If it's true (the default) we quote annotations, and if it's false we don't. I might even go with the wordier quote_annotation_strings=True, as we're only allowing the user to control quoting or not-quoting the annotations when they're strings. But I don't have a strong opinion about that.

[JelleZijlstra]

Good idea, changing that.

[larryhastings]

It's a minor thing, but: globals, locals, and eval_str are passed in to parameters with the same name when calling get_annotations. But annotation_format is passed in to a parameter with a different name (just format). It might be nice to explicitly tell that to the user.

I realize the documentation doesn't explicitly detail where these parameters go, so this would be all-new text. And when I try it in my head it always comes across as clumsy. So... should we even bother to try? Would anybody be confused if we didn't bother to explain it?

[JelleZijlstra]

Good point, I will add a separate sentence about the annotation_format parameter.

[larryhastings]

If I'm reading the code correctly, if this is false (the default) we use repr on annotation values that are strings, and if it's true we skip repr only for strings. So this is a passive operation--if the value is true, we don't do something, and when it's false we do do something. I think that's why this is awkward.

I suggest the clearest way to express this is to flip it. Negate the boolean and rename it quote_annotations=True. If it's true (the default) we quote annotations, and if it's false we don't. I might even go with the wordier quote_annotation_strings=True, as we're only allowing the user to control quoting or not-quoting the annotations when they're strings. But I don't have a strong opinion about that.