Add type hints to Prefix class (#34135)

lib/spack/spack/util/prefix.py

@@ -7,16 +7,17 @@
 This file contains utilities for managing the installation prefix of a package.
 """
 import os
+from typing import Dict
 
 
 class Prefix(str):
-    """This class represents an installation prefix, but provides useful
+    """This class represents an installation prefix, but provides useful attributes for referring
-    attributes for referring to directories inside the prefix.
+    to directories inside the prefix.
 
-    Attributes of this object are created on the fly when you request them,
+    Attributes of this object are created on the fly when you request them, so any of the following
-    so any of the following is valid:
+    are valid:
 
-    >>> prefix = Prefix('/usr')
+    >>> prefix = Prefix("/usr")
     >>> prefix.bin
     /usr/bin
     >>> prefix.lib64
@@ -25,34 +26,56 @@ class Prefix(str):
     /usr/share/man
     >>> prefix.foo.bar.baz
     /usr/foo/bar/baz
-    >>> prefix.join('dashed-directory').bin64
+    >>> prefix.join("dashed-directory").bin64
     /usr/dashed-directory/bin64
 
-    Prefix objects behave identically to strings. In fact, they
+    Prefix objects behave identically to strings. In fact, they subclass ``str``, so operators like
-    subclass ``str``. So operators like ``+`` are legal::
+    ``+`` are legal::
 
-        print('foobar ' + prefix)
+        print("foobar " + prefix)
 
-    This prints ``foobar /usr``. All of this is meant to make custom
+    This prints ``foobar /usr``. All of this is meant to make custom installs easy.
-    installs easy.
     """
 
-    def __getattr__(self, attr):
+    def __getattr__(self, name: str) -> "Prefix":
-        return Prefix(os.path.join(self, attr))
+        """Concatenate a string to a prefix.
 
-    def join(self, string):
+        Useful for strings that are valid variable names.
-        """Concatenates a string to a prefix.
 
-        Parameters:
+        Args:
-            string (str): the string to append to the prefix
+            name: the string to append to the prefix
 
         Returns:
-            Prefix: the newly created installation prefix
+            the newly created installation prefix
+        """
+        return Prefix(os.path.join(self, name))
+
+    def join(self, string: str) -> "Prefix":  # type: ignore[override]
+        """Concatenate a string to a prefix.
+
+        Useful for strings that are not valid variable names. This includes strings containing
+        characters like ``-`` and ``.``.
+
+        Args:
+            string: the string to append to the prefix
+
+        Returns:
+            the newly created installation prefix
         """
         return Prefix(os.path.join(self, string))
 
-    def __getstate__(self):
+    def __getstate__(self) -> Dict[str, str]:
+        """Control how object is pickled.
+
+        Returns:
+            current state of the object
+        """
         return self.__dict__
 
-    def __setstate__(self, d):
+    def __setstate__(self, state: Dict[str, str]) -> None:
-        self.__dict__.update(d)
+        """Control how object is unpickled.
+
+        Args:
+            new state of the object
+        """
+        self.__dict__.update(state)