Assorted typing cleanups

Fix various niggly typing and checker complaints.

Environment.py:

* To avoid modifying a dict-like thing while iterating over it, we did
  .copy(), making an awkward chained construct that checkers don't like.
  Simpler (and the more common idion) is to make a list out of the .keys()
  view, that way you're iterating over that new list and not the dict
  (and save creating a dict copy).
* Another use of copy() was in detecting a CPPDEFINES deque, where we
  want to keep a copy of it and not modify the original - use the deque
  constructor for this instead of calling copy() method.
* Align the names of vars in overridden dunder methods in BuilderDict with
  parent UserDict for more consistency.
* arg2nodes node_factory argument *could* be passed a None, indicate
  that in the signature.
* Multiple uses of CacheDir (it was both an import from CacheDir for type
  checking, and the name of a function in Environment.py). This was confusing
  to at least one type checker, so just use the qualified name.
* The environment Base class _update and _update_onlynew methods
  were annotated to take an EnvironmentBase argument, but in fact they're
  designed to update the internal dict from a passed dict.  Adjusted the
  annotation.
* Used the global Environment hook directly by name rather than fully
  qualified, as SCons.Environment doesn't have an import of itself.  That's
  namespace niggling, because it worked as written.
* The Repository method (public API level) was written to take kwargs and
  pass those on to the FS layer's Repository - which doesn't take kwargs.
  Repository() was never documented as accepting any keyword arguments
  (and no tests ever poked at that usage), so just removed to align the two.
* In VariantDir, make a small readability change and also avoid
  reassigning the function parameters: the index-zero access occurs on the
  call to self.fs.VariantDir, not on the end of the call to arg2nodes.

Node/FS.py: Glob and glob annotation adjusted to show the exclude argument
could also be a single string, as that could be passed down from the public
API level, as documented: "The optional exclude argument may be set to a
pattern or a list of patterns describing files or directories to filter out of
the match list."

Tool/FortranCommon.py: fix an error where returns were Tuple, which is
not imported; changed to tuple.

Signed-off-by: Mats Wichmann <mats@linux.com>

Author: mwichmann

CHANGES.txt

@@ -66,6 +66,8 @@ RELEASE  VERSION/DATE TO BE FILLED IN LATER
       via the SConsignFile(name=None) call.
     - Test framework: tweak module docstrings
     - Test suite: end to end tests don't use assert in result checks
+    - A few more typing cleanups in Environment (and in one case which
+      affected it in the Node package).
 
 
 RELEASE 4.10.1 - Sun, 16 Nov 2025 10:51:57 -0700

SCons/Environment.py

@@ -85,7 +85,6 @@
 
 if TYPE_CHECKING:
     from SCons.Action import ActionBase
-    from SCons.CacheDir import CacheDir
     from SCons.Executor import Executor
     from SCons.Node import Node, NodeInfoBase
     from SCons.Node.FS import DirNode, EntryNode, FileNode
@@ -159,7 +158,7 @@ def apply_tools(
 def copy_non_reserved_keywords(dict_: dict[str, Any]) -> dict[str, Any]:
     """Copy a dict excluding reserved construction variable names."""
     result = semi_deepcopy(dict_)
-    for k in result.copy().keys():
+    for k in list(result.keys()):
         if k in reserved_construction_var_names:
             msg = "Ignoring attempt to set reserved variable `$%s'"
             SCons.Warnings.warn(SCons.Warnings.ReservedVariableWarning, msg % k)
@@ -181,7 +180,7 @@ def _set_BUILDERS(env: EnvironmentBase, key: str, value):
     """Set the BUILDERS construction variable."""
     try:
         bd = env._dict[key]
-        for k in bd.copy().keys():
+        for k in list(bd.keys()):
             del bd[k]
     except KeyError:
         bd = BuilderDict(bd, env)  # XXX use-before-set?
@@ -330,7 +329,7 @@ def _macro_conv(v) -> list:
         env_dict[key] = deque(defines.split())
     elif is_Tuple(defines):
         if len(defines) > 2:
-            raise SCons.Errors.UserError(
+            raise UserError(
                 f"Invalid tuple in CPPDEFINES: {defines!r}, must be a two-tuple"
             )
         env_dict[key] = deque([defines])
@@ -379,14 +378,14 @@ def _macro_conv(v) -> list:
     # A tuple appended to anything should yield -Dkey=value
     elif is_Tuple(val):
         if len(val) > 2:
-            raise SCons.Errors.UserError(
+            raise UserError(
                 f"Invalid tuple added to CPPDEFINES: {val!r}, "
                 "must be a two-tuple"
             )
         if len(val) == 1:
             val = (val[0], None)  # normalize
         if not is_Scalar(val[0]) or not is_Scalar(val[1]):
-            raise SCons.Errors.UserError(
+            raise UserError(
                 f"Invalid tuple added to CPPDEFINES: {val!r}, "
                 "values must be scalar"
             )
@@ -522,19 +521,19 @@ def __semi_deepcopy__(self):
         # object, and indeed just copying would modify the original builder
         raise TypeError( 'cannot semi_deepcopy a BuilderDict' )
 
-    def __setitem__(self, item: str, val) -> None:
+    def __setitem__(self, key: str, item) -> None:
         try:
-            method = getattr(self.env, item).method
+            method = getattr(self.env, key).method
         except AttributeError:
             pass
         else:
             self.env.RemoveMethod(method)
-        super().__setitem__(item, val)
-        BuilderWrapper(self.env, val, item)
+        super().__setitem__(key, item)
+        BuilderWrapper(self.env, item, key)
 
-    def __delitem__(self, item: str) -> None:
-        super().__delitem__(item)
-        delattr(self.env, item)
+    def __delitem__(self, key: str) -> None:
+        super().__delitem__(key)
+        delattr(self.env, key)
 
     # MutableMapping.update() should be fine here with our own __setitem__.
     # def update(self, mapping: dict[str, Any]) -> None:  # type: ignore[override]
@@ -693,7 +692,7 @@ def setdefault(self, key: str, default: Any | None = None) -> Any | None:
     def arg2nodes(
         self,
         args: str | Node | list[str | Node],
-        node_factory: Callable[[str], Node | list[Node]] = _null,  # type: ignore[assignment]
+        node_factory: Callable[[str], Node | list[Node]] | None = _null,  # type: ignore[assignment]
         lookup_list: list[Callable[[str], Node | None]] = _null,  # type: ignore[assignment]
         **kw
     ) -> list[Node]:
@@ -1260,7 +1259,7 @@ def MergeFlags(
                         # the cleanup loops at the end of the outer for loop,
                         # which implicitly gives us a new object.
                         if isinstance(orig, deque):
-                            self[key] = self[key].copy()
+                            self[key] = deque(orig)
                             cast(EnvironmentBase, self).AppendUnique(CPPDEFINES=value, delete_existing=True)
                             continue
                         try:
@@ -1465,21 +1464,21 @@ def get_builder(self, name: str) -> SCons.Builder.BuilderBase | None:
     def validate_CacheDir_class(self, custom_class: type | None = None) -> type:
         """Return a validated custom CacheDir class.
 
-        Validate *custom_class*, which must be derived from
+        Validate that *custom_class*, is derived from
         :class:`SCons.CacheDir.CacheDir`. If *custom_class* is not
         supplied, use the ``CACHEDIR_CLASS`` entry from the environment.
         Return the class if there was no error.
 
         Raises:
-           UserError: if the class is not derived from ``CacheDir``.
+           UserError: if the class is not derived from :class:`~SConsCache.CacheDir`.
         """
         if custom_class is None:
             custom_class = self.get("CACHEDIR_CLASS", SCons.CacheDir.CacheDir)
         if not issubclass(custom_class, SCons.CacheDir.CacheDir):
             raise UserError("Custom CACHEDIR_CLASS %s not derived from CacheDir" % str(custom_class))
         return custom_class
 
-    def get_CacheDir(self) -> CacheDir:
+    def get_CacheDir(self) -> SCons.CacheDir.CacheDir:
         """Return the CacheDir object for this environment, instantiating it if necessary."""
         try:
             path = self._CacheDir_path
@@ -1500,7 +1499,7 @@ def get_CacheDir(self) -> CacheDir:
 
         cd = cachedir_class(path)
         self._last_CacheDir_path: str | None = path
-        self._last_CacheDir: CacheDir = cd
+        self._last_CacheDir: SCons.CacheDir.CacheDir = cd
         return cd
 
     def get_factory(self, factory, default: str = 'File'):
@@ -1576,14 +1575,14 @@ def scanner_map_delete(self, kw=None) -> None:
         except KeyError:
             pass
 
-    def _update(self, other: EnvironmentBase) -> None:
+    def _update(self, other: dict[str, Any]) -> None:
         """Private method to update an environment's consvar dict directly.
 
         Bypasses the normal checks that occur when users try to set items.
         """
         self._dict.update(other)
 
-    def _update_onlynew(self, other: EnvironmentBase) -> None:
+    def _update_onlynew(self, other: dict[str, Any]) -> None:
         """Private method to add new items to an environment's consvar dict.
 
         Only adds items from *other* whose keys do not already appear in
@@ -2703,7 +2702,7 @@ def Entry(self, name: str | Node | list[str | Node], *args, **kw) -> EntryNode |
 
     def Environment(self, **kw) -> EnvironmentBase:
         """Create a construction environment object."""
-        return SCons.Environment.Environment(**self.subst_kw(kw))
+        return Environment(**self.subst_kw(kw))
 
     def Execute(self, action, *args, **kw):
         """Directly execute *action* through an Environment."""
@@ -2822,10 +2821,10 @@ def Pseudo(self, *targets: str | Node | list[str | Node]) -> list[Node]:
             t.set_pseudo()
         return tlist
 
-    def Repository(self, *dirs: str | DirNode | list[str | DirNode], **kw) -> None:
+    def Repository(self, *dirs: str | DirNode | list[str | DirNode]) -> None:
         """Specify Repository directories to search."""
-        dirs = self.arg2nodes(list(dirs), self.fs.Dir)
-        self.fs.Repository(*dirs, **kw)
+        dirs = self.arg2nodes(dirs, self.fs.Dir)
+        self.fs.Repository(*dirs)
 
     def Requires(
         self,
@@ -2970,12 +2969,12 @@ def VariantDir(
 
         This function creates a mapping from the source directory *src_dir* to the
         variant directory *variant_dir*.  If *duplicate* is true (the default),
-        the source files are duplicated into the variant directory; if false,
+        the source files are duplicated into the variant directory; otherwise
         they are not.
         """
-        variant_dir = self.arg2nodes(variant_dir, self.fs.Dir)[0]  # type: ignore[assignment]
-        src_dir = self.arg2nodes(src_dir, self.fs.Dir)[0]  # type: ignore[assignment]
-        self.fs.VariantDir(variant_dir, src_dir, duplicate)  # type: ignore[assignment]
+        variant_dirs = self.arg2nodes(variant_dir, self.fs.Dir)
+        src_dirs = self.arg2nodes(src_dir, self.fs.Dir)
+        self.fs.VariantDir(variant_dirs[0], src_dirs[0], duplicate)
 
     def FindSourceFiles(self, node: str | Node = ".") -> list[EntryNode]:
         """Return the list of all source files under *node*."""

SCons/Node/FS.py

@@ -1570,7 +1570,7 @@ def variant_dir_target_climb(self, orig: Base, dir: DirNode, tail: list[str]) ->
             message = fmt % ' '.join(map(str, targets))
         return targets, message
 
-    def Glob(self, pathname: str, ondisk: bool = True, source: bool = True, strings: bool = False, exclude: list[str] | None = None, cwd: DirNode | None = None) -> list[Node] | list[str]:
+    def Glob(self, pathname: str, ondisk: bool = True, source: bool = True, strings: bool = False, exclude: str | list[str] | None = None, cwd: DirNode | None = None) -> list[Node] | list[str]:
         """
         Globs
 
@@ -2221,7 +2221,7 @@ def walk(self, func, arg) -> None:
         for dirname in [n for n in names if isinstance(entries[n], Dir)]:
             entries[dirname].walk(func, arg)
 
-    def glob(self, pathname: str, ondisk: bool = True, source: bool = False, strings: bool = False, exclude: list[str] | None = None) -> list[Node] | list[str]:
+    def glob(self, pathname: str, ondisk: bool = True, source: bool = False, strings: bool = False, exclude: str | list[str] | None = None) -> list[Node] | list[str]:
         """Returns a list of Nodes (or strings) matching a pathname pattern.
 
         Pathname patterns follow POSIX shell syntax::

SCons/Tool/FortranCommon.py

@@ -59,7 +59,7 @@ def isfortran(env, source) -> bool:
     return False
 
 
-def _fortranEmitter(target, source, env) -> Tuple:
+def _fortranEmitter(target, source, env) -> tuple:
     """Common code for Fortran emitter.
 
     Called by both the static and shared object emitters,
@@ -86,13 +86,13 @@ def _fortranEmitter(target, source, env) -> Tuple:
     return target, source
 
 
-def FortranEmitter(target, source, env) -> Tuple:
+def FortranEmitter(target, source, env) -> tuple:
     """Create emitter for static objects."""
     target, source = _fortranEmitter(target, source, env)
     return StaticObjectEmitter(target, source, env)
 
 
-def ShFortranEmitter(target, source, env) -> Tuple:
+def ShFortranEmitter(target, source, env) -> tuple:
     """Create emitter for shared objects."""
     target, source = _fortranEmitter(target, source, env)
     return SharedObjectEmitter(target, source, env)

SCons/Util/__init__.py

@@ -59,7 +59,7 @@
 import time
 from collections import UserDict, UserList, deque
 from contextlib import suppress
-from typing import Any
+from typing import Any, TypeVar
 from logging import Formatter
 
 # Util split into a package. Make sure things that used to work
@@ -113,6 +113,8 @@
 
 PYPY = hasattr(sys, 'pypy_translation_info')
 
+T = TypeVar('T')
+
 # this string will be hashed if a Node refers to a file that doesn't exist
 # in order to distinguish from a file that exists but is empty.
 NOFILE = "SCONS_MAGIC_MISSING_FILE_STRING"
@@ -539,7 +541,7 @@ def _semi_deepcopy_tuple(obj) -> tuple:
 }
 
 
-def semi_deepcopy(obj):
+def semi_deepcopy(obj: T) -> T:
     copier = _semi_deepcopy_dispatch.get(type(obj))
     if copier:
         return copier(obj)