[pdb] Deprecate curframe_locals (#15177)

stdlib/@tests/stubtest_allowlists/py313.txt

@@ -166,6 +166,8 @@ inspect._ParameterKind.description  # Still exists, but stubtest can't see it
 typing\._SpecialForm.*  # Super-special typing primitive
 typing\.LiteralString  # Super-special typing primitive
 
+# Don't always exist at runtime
+(pdb.Pdb.curframe_locals)?
 
 # ==================================================================
 # Allowlist entries that cannot or should not be fixed; 3.11 to 3.13

stdlib/pdb.pyi

@@ -8,7 +8,7 @@ from linecache import _ModuleGlobals
 from rlcompleter import Completer
 from types import CodeType, FrameType, TracebackType
 from typing import IO, Any, ClassVar, Final, Literal, TypeVar
-from typing_extensions import ParamSpec, Self, TypeAlias
+from typing_extensions import ParamSpec, Self, TypeAlias, deprecated
 
 __all__ = ["run", "pm", "Pdb", "runeval", "runctx", "runcall", "set_trace", "post_mortem", "help"]
 if sys.version_info >= (3, 14):
@@ -60,7 +60,17 @@ class Pdb(Bdb, Cmd):
     stack: list[tuple[FrameType, int]]
     curindex: int
     curframe: FrameType | None
-    curframe_locals: Mapping[str, Any]
+    if sys.version_info >= (3, 13):
+        @property
+        @deprecated("The frame locals reference is no longer cached. Use 'curframe.f_locals' instead.")
+        def curframe_locals(self) -> Mapping[str, Any]: ...
+        @curframe_locals.setter
+        @deprecated(
+            "Setting 'curframe_locals' no longer has any effect as of 3.14. Update the contents of 'curframe.f_locals' instead."
+        )
+        def curframe_locals(self, value: Mapping[str, Any]) -> None: ...
+    else:
+        curframe_locals: Mapping[str, Any]
     if sys.version_info >= (3, 14):
         mode: _Mode | None
         colorize: bool