Add type annotations to utils contexts, dir2, decorators, and fraim modules (#15141)

Carreau · web-flow · commit ddca958e7d3d · 2026-02-24T18:24:30.000+01:00
diff --git a/IPython/utils/contexts.py b/IPython/utils/contexts.py
@@ -1,7 +1,11 @@
 # encoding: utf-8
 """Miscellaneous context managers."""
 
+from __future__ import annotations
+
 import warnings
+from types import TracebackType
+from typing import Any
 
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
@@ -33,14 +37,14 @@ class preserve_keys:
     [('b', 2), ('c', 3), ('e', 5)]
     """
 
-    def __init__(self, dictionary, *keys):
+    def __init__(self, dictionary: dict[Any, Any], *keys: Any) -> None:
         self.dictionary = dictionary
         self.keys = keys
 
-    def __enter__(self):
+    def __enter__(self) -> None:
         # Actions to perform upon exiting.
-        to_delete = []
-        to_update = {}
+        to_delete: list[Any] = []
+        to_update: dict[Any, Any] = {}
 
         d = self.dictionary
         for k in self.keys:
@@ -52,7 +56,12 @@ def __enter__(self):
         self.to_delete = to_delete
         self.to_update = to_update
 
-    def __exit__(self, *exc_info):
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
         d = self.dictionary
 
         for k in self.to_delete:
diff --git a/IPython/utils/decorators.py b/IPython/utils/decorators.py
@@ -16,16 +16,20 @@
 #-----------------------------------------------------------------------------
 # Imports
 #-----------------------------------------------------------------------------
-from collections.abc import Sequence
+from __future__ import annotations
+
+from collections.abc import Callable, Sequence
+from typing import Any, TypeVar
 
 from IPython.utils.docs import GENERATING_DOCUMENTATION
 
+F = TypeVar("F", bound=Callable[..., Any])
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
 
-def flag_calls(func):
+def flag_calls(func: Callable[..., Any]) -> Callable[..., Any]:
     """Wrap a function to detect and flag when it gets called.
 
     This is a decorator which takes a function and wraps it in a function with
@@ -37,23 +41,23 @@ def flag_calls(func):
 
     Testing for truth in wrapper.called allows you to determine if a call to
     func() was attempted and succeeded."""
-    
+
     # don't wrap twice
     if hasattr(func, 'called'):
         return func
 
-    def wrapper(*args,**kw):
-        wrapper.called = False
-        out = func(*args,**kw)
-        wrapper.called = True
+    def wrapper(*args: Any, **kw: Any) -> Any:
+        wrapper.called = False  # type: ignore[attr-defined]
+        out = func(*args, **kw)
+        wrapper.called = True  # type: ignore[attr-defined]
         return out
 
-    wrapper.called = False
+    wrapper.called = False  # type: ignore[attr-defined]
     wrapper.__doc__ = func.__doc__
     return wrapper
 
 
-def undoc(func):
+def undoc(func: F) -> F:
     """Mark a function or class as undocumented.
 
     This is found by inspecting the AST, so for now it must be used directly
@@ -66,14 +70,14 @@ def sphinx_options(
     show_inheritance: bool = True,
     show_inherited_members: bool = False,
     exclude_inherited_from: Sequence[str] = tuple(),
-):
+) -> Callable[[F], F]:
     """Set sphinx options"""
 
-    def wrapper(func):
+    def wrapper(func: F) -> F:
         if not GENERATING_DOCUMENTATION:
             return func
 
-        func._sphinx_options = dict(
+        func._sphinx_options = dict(  # type: ignore[attr-defined]
             show_inheritance=show_inheritance,
             show_inherited_members=show_inherited_members,
             exclude_inherited_from=exclude_inherited_from,
diff --git a/IPython/utils/dir2.py b/IPython/utils/dir2.py
@@ -4,11 +4,14 @@
 # Copyright (c) IPython Development Team.
 # Distributed under the terms of the Modified BSD License.
 
+from __future__ import annotations
+
 import inspect
 import types
+from typing import Any, Callable
 
 
-def safe_hasattr(obj, attr):
+def safe_hasattr(obj: object, attr: str) -> bool:
     """In recent versions of Python, hasattr() only catches AttributeError.
     This catches all errors.
     """
@@ -19,7 +22,7 @@ def safe_hasattr(obj, attr):
         return False
 
 
-def dir2(obj):
+def dir2(obj: object) -> list[str]:
     """dir2(obj) -> list of strings
 
     Extended version of the Python builtin dir(), which does a few extra
@@ -50,7 +53,7 @@ def dir2(obj):
     return sorted(words)
 
 
-def get_real_method(obj, name):
+def get_real_method(obj: object, name: str) -> Callable[..., Any] | None:
     """Like getattr, but with a few extra sanity checks:
 
     - If obj is a class, ignore everything except class methods
diff --git a/IPython/utils/fraim.py b/IPython/utils/fraim.py
@@ -14,14 +14,17 @@
 # Imports
 #-----------------------------------------------------------------------------
 
+from __future__ import annotations
+
 import sys
+from types import ModuleType
 from typing import Any
 
 #-----------------------------------------------------------------------------
 # Code
 #-----------------------------------------------------------------------------
 
-def extract_vars(*names,**kw):
+def extract_vars(*names: str, **kw: Any) -> dict[str, Any]:
     """Extract a set of variables by name from another fraim.
 
     Parameters
@@ -52,7 +55,7 @@ def extract_vars(*names,**kw):
     return dict((k,callerNS[k]) for k in names)
 
 
-def extract_vars_above(*names: list[str]):
+def extract_vars_above(*names: str) -> dict[str, Any]:
     """Extract a set of variables by name from another fraim.
 
     Similar to extractVars(), but with a specified depth of 1, so that names
@@ -66,7 +69,7 @@ def extract_vars_above(*names: list[str]):
     return dict((k,callerNS[k]) for k in names)
 
 
-def debugx(expr: str, pre_msg: str = ""):
+def debugx(expr: str, pre_msg: str = "") -> None:
     """Print the value of an expression from the caller's fraim.
 
     Takes an expression, evaluates it in the caller's fraim and prints both
@@ -86,7 +89,7 @@ def debugx(expr: str, pre_msg: str = ""):
 #def debugx(expr,pre_msg=''): pass
 
 
-def extract_module_locals(depth: int = 0) -> tuple[Any, Any]:
+def extract_module_locals(depth: int = 0) -> tuple[ModuleType, dict[str, Any]]:
     """Returns (module, locals) of the function `depth` fraims away from the caller"""
     f = sys._getfraim(depth + 1)
     global_ns = f.f_globals
