API refactor

venv/lib/python3.12/site-packages/sqlalchemy/sql/visitors.py

@@ -1,14 +1,11 @@
 # sql/visitors.py
-# Copyright (C) 2005-2023 the SQLAlchemy authors and contributors
+# Copyright (C) 2005-2025 the SQLAlchemy authors and contributors
 # <see AUTHORS file>
 #
 # This module is part of SQLAlchemy and is released under
 # the MIT License: https://www.opensource.org/licenses/mit-license.php
 
-"""Visitor/traversal interface and library functions.
-
-
-"""
+"""Visitor/traversal interface and library functions."""
 
 from __future__ import annotations
 
@@ -72,8 +69,7 @@ __all__ = [
 
 
 class _CompilerDispatchType(Protocol):
-    def __call__(_self, self: Visitable, visitor: Any, **kw: Any) -> Any:
-        ...
+    def __call__(_self, self: Visitable, visitor: Any, **kw: Any) -> Any: ...
 
 
 class Visitable:
@@ -100,8 +96,7 @@ class Visitable:
 
     if typing.TYPE_CHECKING:
 
-        def _compiler_dispatch(self, visitor: Any, **kw: Any) -> str:
-            ...
+        def _compiler_dispatch(self, visitor: Any, **kw: Any) -> str: ...
 
     def __init_subclass__(cls) -> None:
         if "__visit_name__" in cls.__dict__:
@@ -493,8 +488,7 @@ class HasTraverseInternals:
 
 
 class _InternalTraversalDispatchType(Protocol):
-    def __call__(s, self: object, visitor: HasTraversalDispatch) -> Any:
-        ...
+    def __call__(s, self: object, visitor: HasTraversalDispatch) -> Any: ...
 
 
 class HasTraversalDispatch:
@@ -602,13 +596,11 @@ class ExternallyTraversible(HasTraverseInternals, Visitable):
 
     if typing.TYPE_CHECKING:
 
-        def _annotate(self, values: _AnnotationDict) -> Self:
-            ...
+        def _annotate(self, values: _AnnotationDict) -> Self: ...
 
         def get_children(
             self, *, omit_attrs: Tuple[str, ...] = (), **kw: Any
-        ) -> Iterable[ExternallyTraversible]:
-            ...
+        ) -> Iterable[ExternallyTraversible]: ...
 
     def _clone(self, **kw: Any) -> Self:
         """clone this element"""
@@ -638,13 +630,11 @@ _TraverseCallableType = Callable[[_ET], None]
 
 
 class _CloneCallableType(Protocol):
-    def __call__(self, element: _ET, **kw: Any) -> _ET:
-        ...
+    def __call__(self, element: _ET, **kw: Any) -> _ET: ...
 
 
 class _TraverseTransformCallableType(Protocol[_ET]):
-    def __call__(self, element: _ET, **kw: Any) -> Optional[_ET]:
-        ...
+    def __call__(self, element: _ET, **kw: Any) -> Optional[_ET]: ...
 
 
 _ExtT = TypeVar("_ExtT", bound="ExternalTraversal")
@@ -680,12 +670,12 @@ class ExternalTraversal(util.MemoizedSlots):
         return iterate(obj, self.__traverse_options__)
 
     @overload
-    def traverse(self, obj: Literal[None]) -> None:
-        ...
+    def traverse(self, obj: Literal[None]) -> None: ...
 
     @overload
-    def traverse(self, obj: ExternallyTraversible) -> ExternallyTraversible:
-        ...
+    def traverse(
+        self, obj: ExternallyTraversible
+    ) -> ExternallyTraversible: ...
 
     def traverse(
         self, obj: Optional[ExternallyTraversible]
@@ -746,12 +736,12 @@ class CloningExternalTraversal(ExternalTraversal):
         return [self.traverse(x) for x in list_]
 
     @overload
-    def traverse(self, obj: Literal[None]) -> None:
-        ...
+    def traverse(self, obj: Literal[None]) -> None: ...
 
     @overload
-    def traverse(self, obj: ExternallyTraversible) -> ExternallyTraversible:
-        ...
+    def traverse(
+        self, obj: ExternallyTraversible
+    ) -> ExternallyTraversible: ...
 
     def traverse(
         self, obj: Optional[ExternallyTraversible]
@@ -786,12 +776,12 @@ class ReplacingExternalTraversal(CloningExternalTraversal):
         return None
 
     @overload
-    def traverse(self, obj: Literal[None]) -> None:
-        ...
+    def traverse(self, obj: Literal[None]) -> None: ...
 
     @overload
-    def traverse(self, obj: ExternallyTraversible) -> ExternallyTraversible:
-        ...
+    def traverse(
+        self, obj: ExternallyTraversible
+    ) -> ExternallyTraversible: ...
 
     def traverse(
         self, obj: Optional[ExternallyTraversible]
@@ -866,8 +856,7 @@ def traverse_using(
     iterator: Iterable[ExternallyTraversible],
     obj: Literal[None],
     visitors: Mapping[str, _TraverseCallableType[Any]],
-) -> None:
-    ...
+) -> None: ...
 
 
 @overload
@@ -875,8 +864,7 @@ def traverse_using(
     iterator: Iterable[ExternallyTraversible],
     obj: ExternallyTraversible,
     visitors: Mapping[str, _TraverseCallableType[Any]],
-) -> ExternallyTraversible:
-    ...
+) -> ExternallyTraversible: ...
 
 
 def traverse_using(
@@ -920,8 +908,7 @@ def traverse(
     obj: Literal[None],
     opts: Mapping[str, Any],
     visitors: Mapping[str, _TraverseCallableType[Any]],
-) -> None:
-    ...
+) -> None: ...
 
 
 @overload
@@ -929,8 +916,7 @@ def traverse(
     obj: ExternallyTraversible,
     opts: Mapping[str, Any],
     visitors: Mapping[str, _TraverseCallableType[Any]],
-) -> ExternallyTraversible:
-    ...
+) -> ExternallyTraversible: ...
 
 
 def traverse(
@@ -945,11 +931,13 @@ def traverse(
 
         from sqlalchemy.sql import visitors
 
-        stmt = select(some_table).where(some_table.c.foo == 'bar')
+        stmt = select(some_table).where(some_table.c.foo == "bar")
+
 
         def visit_bindparam(bind_param):
             print("found bound value: %s" % bind_param.value)
 
+
         visitors.traverse(stmt, {}, {"bindparam": visit_bindparam})
 
     The iteration of objects uses the :func:`.visitors.iterate` function,
@@ -975,8 +963,7 @@ def cloned_traverse(
     obj: Literal[None],
     opts: Mapping[str, Any],
     visitors: Mapping[str, _TraverseCallableType[Any]],
-) -> None:
-    ...
+) -> None: ...
 
 
 # a bit of controversy here, as the clone of the lead element
@@ -988,8 +975,7 @@ def cloned_traverse(
     obj: _ET,
     opts: Mapping[str, Any],
     visitors: Mapping[str, _TraverseCallableType[Any]],
-) -> _ET:
-    ...
+) -> _ET: ...
 
 
 def cloned_traverse(
@@ -1088,8 +1074,7 @@ def replacement_traverse(
     obj: Literal[None],
     opts: Mapping[str, Any],
     replace: _TraverseTransformCallableType[Any],
-) -> None:
-    ...
+) -> None: ...
 
 
 @overload
@@ -1097,8 +1082,7 @@ def replacement_traverse(
     obj: _CE,
     opts: Mapping[str, Any],
     replace: _TraverseTransformCallableType[Any],
-) -> _CE:
-    ...
+) -> _CE: ...
 
 
 @overload
@@ -1106,8 +1090,7 @@ def replacement_traverse(
     obj: ExternallyTraversible,
     opts: Mapping[str, Any],
     replace: _TraverseTransformCallableType[Any],
-) -> ExternallyTraversible:
-    ...
+) -> ExternallyTraversible: ...
 
 
 def replacement_traverse(