Kudos for addressing this issue so quickly!

When ForwardRef.__extra_names__ is None, __resolved_str__ is identical to __forward_arg__, which should be a string containing the code that was evaluated to produce the ForwardRef. In short, adding __resolved_str__ did not eliminate the __forward_arg__ leak. That interface is still broken.

Renaming the new property might help, but I would not be surprised if additional effort is needed.

(I can imagine a world where evaluate_forward_ref is deprecated and ForwardRef.evaluate recursively evaluates nested forward references as needed.)

In short, adding __resolved_str__ did not eliminate the __forward_arg__ leak. That interface is still broken.

I think the key is not eliminating the __forward_arg__ leak, but preventing the leak of internal names like __annotationlib_name_1__.

When ForwardRef.__extra_names__ is None, I believe directly returning __forward_arg__ would not leak the internal names.

Besides, this raises a question for me: should we add __resolved_arg__ documentation, since __forward_arg__ is documented?

I think the key is not eliminating the __forward_arg__ leak, but preventing the leak of internal names like __annotationlib_name_1__.

I think we agree. When I wrote "the __forward_arg__ leak" I should have written "leaking internal names via __forward_arg__."

The description of __forward_arg__ in the documentation is a de facto contract. Its value should be appropriate when evaluating a forward reference with format=Format.STRING, and probably is appropriate when forward references are strings. (In my code, forward references are never strings.)

Note that __forward_arg__ is supported by annotationlib.pyi whereas __resolved_str__ is not. At this point, the new property is just an implementation detail. I mentioned renaming it, because I think it tries to be what __forward_arg__ should be.

I think the documentation isn't entirely accurate for .__forward_arg__ at this point, it's more like:

A string containing the code that will be evaluated when attempting to resolve the ForwardRef. This may not be exactly equivalent to the original source code.

I did view .__resolved_str__ as more of an internal detail, expecting that (outside of the class itself) it would be accessed through .evaluate(format=Format.STRING).

My primary goal is preventing internal name exposure via Sphinx. PEP-749 suggests that __forward_arg__ is less important than evaluate_forward_ref, so I belatedly regret calling attention to this attribute and hope this pull request is approved/merged as-is.

Yes, I think any change in documentation can be a separate issue and PR.

typing probably already uses enough of ForwardRef internals that it doesn't matter that it uses .__resolved_str__ as a shortcut, but in general the public way to get this should be through .evaluate(format=Format.STRING) unless we do decide to guarantee and document .__resolved_str__.

Otherwise this looks fine to me.

@JelleZijlstra Do you mind reviewing this PR again when you have a chance?

Thanks @ByteFlowing1337 for the PR, and @JelleZijlstra for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14, 3.15.
🐍🍒⛏🤖

Sorry, @ByteFlowing1337 and @JelleZijlstra, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker f75028f7ceebee4cbeb46bf040834e2005d57436 3.14

GH-152935 is a backport of this pull request to the 3.15 branch.