gh-138098: Clarify strong references in PyDict_Next docs for free-threaded build

[PrinceNaroliya]

This PR updates the documentation of :c:func:PyDict_Next to clarify the
handling of references in the free-threaded build.

Currently, the docs mention that PyDict_Next is not safe in the free-threaded
build and suggest using a critical section. However, the returned pkey and
pvalue are borrowed references, which are only valid while the critical
section is held. If they need to be accessed outside of that critical section,
strong references must be created.

This PR adds a .. note:: block explaining this behavior explicitly, and
suggests using :c:func:Py_NewRef to obtain strong references.

Rationale

• Makes the documentation safer and clearer for users of the free-threaded
  build.
• Resolves issue gh-138098.
• Matches the behavior noted in gh-119438.

Example of new docs rendering

---

Thanks!

---

📚 Documentation preview 📚: https://cpython-previews--138106.org.readthedocs.build/en/138106/c-api/dict.html#c.PyDict_Next

[ZeroIntensity]

Looks mostly fine, we just need to add links to the terms.

[PrinceNaroliya]

Thanks for the helpful reviews!
I’ve applied the suggested changes:

• Added glossary links for free threaded, borrowed reference, and strong reference
• Clarified the wording about usage outside/suspended critical sections
• Mentioned creating strong references with :c:func:Py_NewRef

Please let me know if anything else needs to be updated ✅

[eendebakpt]

The text itself is good now. But the position in the documentation is a bit odd. The note is separated from the other text on free threading. For that reason, I would move the note down a bit.

[PrinceNaroliya]

"I have tried adding the .. note:: directive in Sphinx multiple times.
When I place the note at the top, it renders correctly as a highlighted note box.
However, when I try to paste the same note at the bottom, it only appears as normal text and does not display as a note.
I have checked indentation, blank lines, and code-block formatting, but the problem persists.
It seems to be an issue with how Sphinx handles notes at the bottom rather than a syntax error.

[ZeroIntensity]

It works for me:

[PrinceNaroliya]

I have fixed the issue, everything seems correct now. Previously the note was not displaying properly at the top, but now it appears correctly at the bottom

[ZeroIntensity]

Thanks, this looks good to me.

@eendebakpt As the issue author, are you happy with this? If so, I'll merge this.

[eendebakpt]

Looks good to me. Thanks @PrinceNaroliya

[PrinceNaroliya]

Thanks for the helpful reviews! I’m happy with the changes and everything looks good now.

[miss-islington-app]

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

[bedevere-app]

GH-138141 is a backport of this pull request to the 3.14 branch.