feature: add ClassTypeHint.recurse_bases()

Author: NiklasRosenstein

.changelog/_unreleased.toml

@@ -3,3 +3,9 @@ id = "a5578e7f-32ca-442e-b52a-e6a16c573c35"
 type = "fix"
 description = "`ClassTypeHint.bases` now falls back to the types actual base classes if it is not a generic type"
 author = "@NiklasRosenstein"
+
+[[entries]]
+id = "5883174c-0b7b-4be0-b28e-b7c69922f551"
+type = "feature"
+description = "add `ClassTypeHint.recurse_bases()`"
+author = "@NiklasRosenstein"

src/typeapi/typehint.py

@@ -1,10 +1,24 @@
 import abc
 import sys
-from collections import ChainMap
+from collections import ChainMap, deque
 from types import ModuleType
-from typing import Any, Dict, Generic, Iterator, List, Mapping, MutableMapping, Tuple, TypeVar, Union, cast, overload
+from typing import (
+    Any,
+    Dict,
+    Generator,
+    Generic,
+    Iterator,
+    List,
+    Mapping,
+    MutableMapping,
+    Tuple,
+    TypeVar,
+    Union,
+    cast,
+    overload,
+)
 
-from typing_extensions import Annotated
+from typing_extensions import Annotated, Literal
 
 from .utils import (
     ForwardRef,
@@ -283,6 +297,38 @@ def get_parameter_map(self) -> Dict[Any, Any]:
         # use self.parameters.
         return dict(zip(TypeHint(self.type).parameters, self.args))
 
+    def recurse_bases(
+        self, order: Literal["dfs", "bfs"] = "bfs"
+    ) -> Generator["ClassTypeHint", Union[Literal["skip"], None], None]:
+        """
+        Iterate over all base classes of this type hint, and continues recursively. The iteration order is
+        determined by the *order* parameter, which can be either depth-first or breadh-first. If the generator
+        receives the string `"skip"` from the caller, it will skip the bases of the last yielded type.
+        """
+
+        # Find the item type in the base classes of the collection type.
+        bases = deque([self])
+
+        while bases:
+            current = bases.popleft()
+            if not isinstance(current, ClassTypeHint):
+                raise RuntimeError(
+                    f"Expected to find a ClassTypeHint in the base classes of {self!r}, found {current!r} instead."
+                )
+
+            response = yield current
+            if response == "skip":
+                continue
+
+            current_bases = cast(List[ClassTypeHint], [TypeHint(x, current.type).evaluate() for x in current.bases])
+
+            if order == "bfs":
+                bases.extend(current_bases)
+            elif order == "dfs":
+                bases.extendleft(reversed(current_bases))
+            else:
+                raise ValueError(f"Invalid order {order!r}")
+
 
 class UnionTypeHint(TypeHint):
     def has_none_type(self) -> bool:

src/typeapi/typehint_test.py

@@ -497,3 +497,39 @@ def test__TypeHint__repeated() -> None:
     assert hint.args == (int,)
     assert hint.parameters == ()
     assert hint.repeated
+
+
+def test__ClassTypeHint__iter_all_bases() -> None:
+    class A:
+        pass
+
+    class B(A, int):
+        pass
+
+    class C(B, Generic[T]):
+        pass
+
+    hint = TypeHint(C)
+    assert isinstance(hint, ClassTypeHint)
+    assert hint.type is C
+    assert hint.bases == (B, Generic[T])
+    assert list(hint.recurse_bases("bfs")) == [
+        TypeHint(C),
+        TypeHint(B),
+        TypeHint(Generic[T]),
+        TypeHint(A),
+        TypeHint(int),
+        TypeHint(object),
+        TypeHint(object),
+        TypeHint(object),
+    ]
+    assert list(hint.recurse_bases("dfs")) == [
+        TypeHint(C),
+        TypeHint(B),
+        TypeHint(A),
+        TypeHint(object),
+        TypeHint(int),
+        TypeHint(object),
+        TypeHint(Generic[T]),
+        TypeHint(object),
+    ]