# sql/visitors.py
# Copyright (C) 2005-2024 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.


"""

from __future__ import annotations

from collections import deque
from enum import Enum
import itertools
import operator
import typing
from typing import Any
from typing import Callable
from typing import cast
from typing import ClassVar
from typing import Dict
from typing import Iterable
from typing import Iterator
from typing import List
from typing import Mapping
from typing import Optional
from typing import overload
from typing import Tuple
from typing import Type
from typing import TYPE_CHECKING
from typing import TypeVar
from typing import Union

from .. import exc
from .. import util
from ..util import langhelpers
from ..util._has_cy import HAS_CYEXTENSION
from ..util.typing import Literal
from ..util.typing import Protocol
from ..util.typing import Self

if TYPE_CHECKING:
    from .annotation import _AnnotationDict
    from .elements import ColumnElement

if typing.TYPE_CHECKING or not HAS_CYEXTENSION:
    from ._py_util import prefix_anon_map as prefix_anon_map
    from ._py_util import cache_anon_map as anon_map
else:
    from sqlalchemy.cyextension.util import (  # noqa: F401,E501
        prefix_anon_map as prefix_anon_map,
    )
    from sqlalchemy.cyextension.util import (  # noqa: F401,E501
        cache_anon_map as anon_map,
    )


__all__ = [
    "iterate",
    "traverse_using",
    "traverse",
    "cloned_traverse",
    "replacement_traverse",
    "Visitable",
    "ExternalTraversal",
    "InternalTraversal",
    "anon_map",
]


class _CompilerDispatchType(Protocol):
    def __call__(_self, self: Visitable, visitor: Any, **kw: Any) -> Any: ...


class Visitable:
    """Base class for visitable objects.

    :class:`.Visitable` is used to implement the SQL compiler dispatch
    functions.    Other forms of traversal such as for cache key generation
    are implemented separately using the :class:`.HasTraverseInternals`
    interface.

    .. versionchanged:: 2.0  The :class:`.Visitable` class was named
       :class:`.Traversible` in the 1.4 series; the name is changed back
       to :class:`.Visitable` in 2.0 which is what it was prior to 1.4.

       Both names remain importable in both 1.4 and 2.0 versions.

    """

    __slots__ = ()

    __visit_name__: str

    _original_compiler_dispatch: _CompilerDispatchType

    if typing.TYPE_CHECKING:

        def _compiler_dispatch(self, visitor: Any, **kw: Any) -> str: ...

    def __init_subclass__(cls) -> None:
        if "__visit_name__" in cls.__dict__:
            cls._generate_compiler_dispatch()
        super().__init_subclass__()

    @classmethod
    def _generate_compiler_dispatch(cls) -> None:
        visit_name = cls.__visit_name__

        if "_compiler_dispatch" in cls.__dict__:
            # class has a fixed _compiler_dispatch() method.
            # copy it to "original" so that we can get it back if
            # sqlalchemy.ext.compiles overrides it.
            cls._original_compiler_dispatch = cls._compiler_dispatch
            return

        if not isinstance(visit_name, str):
            raise exc.InvalidRequestError(
                f"__visit_name__ on class {cls.__name__} must be a string "
                "at the class level"
            )

        name = "visit_%s" % visit_name
        getter = operator.attrgetter(name)

        def _compiler_dispatch(
            self: Visitable, visitor: Any, **kw: Any
        ) -> str:
            """Look for an attribute named "visit_<visit_name>" on the
            visitor, and call it with the same kw params.

            """
            try:
                meth = getter(visitor)
            except AttributeError as err:
                return visitor.visit_unsupported_compilation(self, err, **kw)  # type: ignore  # noqa: E501
            else:
                return meth(self, **kw)  # type: ignore  # noqa: E501

        cls._compiler_dispatch = (  # type: ignore
            cls._original_compiler_dispatch
        ) = _compiler_dispatch

    def __class_getitem__(cls, key: Any) -> Any:
        # allow generic classes in py3.9+
        return cls


class InternalTraversal(Enum):
    r"""Defines visitor symbols used for internal traversal.

    The :class:`.InternalTraversal` class is used in two ways.  One is that
    it can serve as the superclass for an object that implements the
    various visit methods of the class.   The other is that the symbols
    themselves of :class:`.InternalTraversal` are used within
    the ``_traverse_internals`` collection.   Such as, the :class:`.Case`
    object defines ``_traverse_internals`` as ::

        class Case(ColumnElement[_T]):
            _traverse_internals = [
                ("value", InternalTraversal.dp_clauseelement),
                ("whens", InternalTraversal.dp_clauseelement_tuples),
                ("else_", InternalTraversal.dp_clauseelement),
            ]

    Above, the :class:`.Case` class indicates its internal state as the
    attributes named ``value``, ``whens``, and ``else_``.    They each
    link to an :class:`.InternalTraversal` method which indicates the type
    of datastructure to which each attribute refers.

    Using the ``_traverse_internals`` structure, objects of type
    :class:`.InternalTraversible` will have the following methods automatically
    implemented:

    * :meth:`.HasTraverseInternals.get_children`

    * :meth:`.HasTraverseInternals._copy_internals`

    * :meth:`.HasCacheKey._gen_cache_key`

    Subclasses can also implement these methods directly, particularly for the
    :meth:`.HasTraverseInternals._copy_internals` method, when special steps
    are needed.

    .. versionadded:: 1.4

    """

    dp_has_cache_key = "HC"
    """Visit a :class:`.HasCacheKey` object."""

    dp_has_cache_key_list = "HL"
    """Visit a list of :class:`.HasCacheKey` objects."""

    dp_clauseelement = "CE"
    """Visit a :class:`_expression.ClauseElement` object."""

    dp_fromclause_canonical_column_collection = "FC"
    """Visit a :class:`_expression.FromClause` object in the context of the
    ``columns`` attribute.

    The column collection is "canonical", meaning it is the originally
    defined location of the :class:`.ColumnClause` objects.   Right now
    this means that the object being visited is a
    :class:`_expression.TableClause`
    or :class:`_schema.Table` object only.

    """

    dp_clauseelement_tuples = "CTS"
    """Visit a list of tuples which contain :class:`_expression.ClauseElement`
    objects.

    """

    dp_clauseelement_list = "CL"
    """Visit a list of :class:`_expression.ClauseElement` objects.

    """

    dp_clauseelement_tuple = "CT"
    """Visit a tuple of :class:`_expression.ClauseElement` objects.

    """

    dp_executable_options = "EO"

    dp_with_context_options = "WC"

    dp_fromclause_ordered_set = "CO"
    """Visit an ordered set of :class:`_expression.FromClause` objects. """

    dp_string = "S"
    """Visit a plain string value.

    Examples include table and column names, bound parameter keys, special
    keywords such as "UNION", "UNION ALL".

    The string value is considered to be significant for cache key
    generation.

    """

    dp_string_list = "SL"
    """Visit a list of strings."""

    dp_anon_name = "AN"
    """Visit a potentially "anonymized" string value.

    The string value is considered to be significant for cache key
    generation.

    """

    dp_boolean = "B"
    """Visit a boolean value.

    The boolean value is considered to be significant for cache key
    generation.

    """

    dp_operator = "O"
    """Visit an operator.

    The operator is a function from the :mod:`sqlalchemy.sql.operators`
    module.

    The operator value is considered to be significant for cache key
    generation.

    """

    dp_type = "T"
    """Visit a :class:`.TypeEngine` object

    The type object is considered to be significant for cache key
    generation.

    """

    dp_plain_dict = "PD"
    """Visit a dictionary with string keys.

    The keys of the dictionary should be strings, the values should
    be immutable and hashable.   The dictionary is considered to be
    significant for cache key generation.

    """

    dp_dialect_options = "DO"
    """Visit a dialect options structure."""

    dp_string_clauseelement_dict = "CD"
    """Visit a dictionary of string keys to :class:`_expression.ClauseElement`
    objects.

    """

    dp_string_multi_dict = "MD"
    """Visit a dictionary of string keys to values which may either be
    plain immutable/hashable or :class:`.HasCacheKey` objects.

    """

    dp_annotations_key = "AK"
    """Visit the _annotations_cache_key element.

    This is a dictionary of additional information about a ClauseElement
    that modifies its role.  It should be included when comparing or caching
    objects, however generating this key is relatively expensive.   Visitors
    should check the "_annotations" dict for non-None first before creating
    this key.

    """

    dp_plain_obj = "PO"
    """Visit a plain python object.

    The value should be immutable and hashable, such as an integer.
    The value is considered to be significant for cache key generation.

    """

    dp_named_ddl_element = "DD"
    """Visit a simple named DDL element.

    The current object used by this method is the :class:`.Sequence`.

    The object is only considered to be important for cache key generation
    as far as its name, but not any other aspects of it.

    """

    dp_prefix_sequence = "PS"
    """Visit the sequence represented by :class:`_expression.HasPrefixes`
    or :class:`_expression.HasSuffixes`.

    """

    dp_table_hint_list = "TH"
    """Visit the ``_hints`` collection of a :class:`_expression.Select`
    object.

    """

    dp_setup_join_tuple = "SJ"

    dp_memoized_select_entities = "ME"

    dp_statement_hint_list = "SH"
    """Visit the ``_statement_hints`` collection of a
    :class:`_expression.Select`
    object.

    """

    dp_unknown_structure = "UK"
    """Visit an unknown structure.

    """

    dp_dml_ordered_values = "DML_OV"
    """Visit the values() ordered tuple list of an
    :class:`_expression.Update` object."""

    dp_dml_values = "DML_V"
    """Visit the values() dictionary of a :class:`.ValuesBase`
    (e.g. Insert or Update) object.

    """

    dp_dml_multi_values = "DML_MV"
    """Visit the values() multi-valued list of dictionaries of an
    :class:`_expression.Insert` object.

    """

    dp_propagate_attrs = "PA"
    """Visit the propagate attrs dict.  This hardcodes to the particular
    elements we care about right now."""

    """Symbols that follow are additional symbols that are useful in
    caching applications.

    Traversals for :class:`_expression.ClauseElement` objects only need to use
    those symbols present in :class:`.InternalTraversal`.  However, for
    additional caching use cases within the ORM, symbols dealing with the
    :class:`.HasCacheKey` class are added here.

    """

    dp_ignore = "IG"
    """Specify an object that should be ignored entirely.

    This currently applies function call argument caching where some
    arguments should not be considered to be part of a cache key.

    """

    dp_inspectable = "IS"
    """Visit an inspectable object where the return value is a
    :class:`.HasCacheKey` object."""

    dp_multi = "M"
    """Visit an object that may be a :class:`.HasCacheKey` or may be a
    plain hashable object."""

    dp_multi_list = "MT"
    """Visit a tuple containing elements that may be :class:`.HasCacheKey` or
    may be a plain hashable object."""

    dp_has_cache_key_tuples = "HT"
    """Visit a list of tuples which contain :class:`.HasCacheKey`
    objects.

    """

    dp_inspectable_list = "IL"
    """Visit a list of inspectable objects which upon inspection are
    HasCacheKey objects."""


_TraverseInternalsType = List[Tuple[str, InternalTraversal]]
"""a structure that defines how a HasTraverseInternals should be
traversed.

This structure consists of a list of (attributename, internaltraversal)
tuples, where the "attributename" refers to the name of an attribute on an
instance of the HasTraverseInternals object, and "internaltraversal" refers
to an :class:`.InternalTraversal` enumeration symbol defining what kind
of data this attribute stores, which indicates to the traverser how it should
be handled.

"""


class HasTraverseInternals:
    """base for classes that have a "traverse internals" element,
    which defines all kinds of ways of traversing the elements of an object.

    Compared to :class:`.Visitable`, which relies upon an external visitor to
    define how the object is travered (i.e. the :class:`.SQLCompiler`), the
    :class:`.HasTraverseInternals` interface allows classes to define their own
    traversal, that is, what attributes are accessed and in what order.

    """

    __slots__ = ()

    _traverse_internals: _TraverseInternalsType

    _is_immutable: bool = False

    @util.preload_module("sqlalchemy.sql.traversals")
    def get_children(
        self, *, omit_attrs: Tuple[str, ...] = (), **kw: Any
    ) -> Iterable[HasTraverseInternals]:
        r"""Return immediate child :class:`.visitors.HasTraverseInternals`
        elements of this :class:`.visitors.HasTraverseInternals`.

        This is used for visit traversal.

        \**kw may contain flags that change the collection that is
        returned, for example to return a subset of items in order to
        cut down on larger traversals, or to return child items from a
        different context (such as schema-level collections instead of
        clause-level).

        """

        traversals = util.preloaded.sql_traversals

        try:
            traverse_internals = self._traverse_internals
        except AttributeError:
            # user-defined classes may not have a _traverse_internals
            return []

        dispatch = traversals._get_children.run_generated_dispatch
        return itertools.chain.from_iterable(
            meth(obj, **kw)
            for attrname, obj, meth in dispatch(
                self, traverse_internals, "_generated_get_children_traversal"
            )
            if attrname not in omit_attrs and obj is not None
        )


class _InternalTraversalDispatchType(Protocol):
    def __call__(s, self: object, visitor: HasTraversalDispatch) -> Any: ...


class HasTraversalDispatch:
    r"""Define infrastructure for classes that perform internal traversals

    .. versionadded:: 2.0

    """

    __slots__ = ()

    _dispatch_lookup: ClassVar[Dict[Union[InternalTraversal, str], str]] = {}

    def dispatch(self, visit_symbol: InternalTraversal) -> Callable[..., Any]:
        """Given a method from :class:`.HasTraversalDispatch`, return the
        corresponding method on a subclass.

        """
        name = _dispatch_lookup[visit_symbol]
        return getattr(self, name, None)  # type: ignore

    def run_generated_dispatch(
        self,
        target: object,
        internal_dispatch: _TraverseInternalsType,
        generate_dispatcher_name: str,
    ) -> Any:
        dispatcher: _InternalTraversalDispatchType
        try:
            dispatcher = target.__class__.__dict__[generate_dispatcher_name]
        except KeyError:
            # traversals.py -> _preconfigure_traversals()
            # may be used to run these ahead of time, but
            # is not enabled right now.
            # this block will generate any remaining dispatchers.
            dispatcher = self.generate_dispatch(
                target.__class__, internal_dispatch, generate_dispatcher_name
            )
        return dispatcher(target, self)

    def generate_dispatch(
        self,
        target_cls: Type[object],
        internal_dispatch: _TraverseInternalsType,
        generate_dispatcher_name: str,
    ) -> _InternalTraversalDispatchType:
        dispatcher = self._generate_dispatcher(
            internal_dispatch, generate_dispatcher_name
        )
        # assert isinstance(target_cls, type)
        setattr(target_cls, generate_dispatcher_name, dispatcher)
        return dispatcher

    def _generate_dispatcher(
        self, internal_dispatch: _TraverseInternalsType, method_name: str
    ) -> _InternalTraversalDispatchType:
        names = []
        for attrname, visit_sym in internal_dispatch:
            meth = self.dispatch(visit_sym)
            if meth is not None:
                visit_name = _dispatch_lookup[visit_sym]
                names.append((attrname, visit_name))

        code = (
            ("    return [\n")
            + (
                ", \n".join(
                    "        (%r, self.%s, visitor.%s)"
                    % (attrname, attrname, visit_name)
                    for attrname, visit_name in names
                )
            )
            + ("\n    ]\n")
        )
        meth_text = ("def %s(self, visitor):\n" % method_name) + code + "\n"
        return cast(
            _InternalTraversalDispatchType,
            langhelpers._exec_code_in_env(meth_text, {}, method_name),
        )


ExtendedInternalTraversal = InternalTraversal


def _generate_traversal_dispatch() -> None:
    lookup = _dispatch_lookup

    for sym in InternalTraversal:
        key = sym.name
        if key.startswith("dp_"):
            visit_key = key.replace("dp_", "visit_")
            sym_name = sym.value
            assert sym_name not in lookup, sym_name
            lookup[sym] = lookup[sym_name] = visit_key


_dispatch_lookup = HasTraversalDispatch._dispatch_lookup
_generate_traversal_dispatch()


class ExternallyTraversible(HasTraverseInternals, Visitable):
    __slots__ = ()

    _annotations: Mapping[Any, Any] = util.EMPTY_DICT

    if typing.TYPE_CHECKING:

        def _annotate(self, values: _AnnotationDict) -> Self: ...

        def get_children(
            self, *, omit_attrs: Tuple[str, ...] = (), **kw: Any
        ) -> Iterable[ExternallyTraversible]: ...

    def _clone(self, **kw: Any) -> Self:
        """clone this element"""
        raise NotImplementedError()

    def _copy_internals(
        self, *, omit_attrs: Tuple[str, ...] = (), **kw: Any
    ) -> None:
        """Reassign internal elements to be clones of themselves.

        Called during a copy-and-traverse operation on newly
        shallow-copied elements to create a deep copy.

        The given clone function should be used, which may be applying
        additional transformations to the element (i.e. replacement
        traversal, cloned traversal, annotations).

        """
        raise NotImplementedError()


_ET = TypeVar("_ET", bound=ExternallyTraversible)

_CE = TypeVar("_CE", bound="ColumnElement[Any]")

_TraverseCallableType = Callable[[_ET], None]


class _CloneCallableType(Protocol):
    def __call__(self, element: _ET, **kw: Any) -> _ET: ...


class _TraverseTransformCallableType(Protocol[_ET]):
    def __call__(self, element: _ET, **kw: Any) -> Optional[_ET]: ...


_ExtT = TypeVar("_ExtT", bound="ExternalTraversal")


class ExternalTraversal(util.MemoizedSlots):
    """Base class for visitor objects which can traverse externally using
    the :func:`.visitors.traverse` function.

    Direct usage of the :func:`.visitors.traverse` function is usually
    preferred.

    """

    __slots__ = ("_visitor_dict", "_next")

    __traverse_options__: Dict[str, Any] = {}
    _next: Optional[ExternalTraversal]

    def traverse_single(self, obj: Visitable, **kw: Any) -> Any:
        for v in self.visitor_iterator:
            meth = getattr(v, "visit_%s" % obj.__visit_name__, None)
            if meth:
                return meth(obj, **kw)

    def iterate(
        self, obj: Optional[ExternallyTraversible]
    ) -> Iterator[ExternallyTraversible]:
        """Traverse the given expression structure, returning an iterator
        of all elements.

        """
        return iterate(obj, self.__traverse_options__)

    @overload
    def traverse(self, obj: Literal[None]) -> None: ...

    @overload
    def traverse(
        self, obj: ExternallyTraversible
    ) -> ExternallyTraversible: ...

    def traverse(
        self, obj: Optional[ExternallyTraversible]
    ) -> Optional[ExternallyTraversible]:
        """Traverse and visit the given expression structure."""

        return traverse(obj, self.__traverse_options__, self._visitor_dict)

    def _memoized_attr__visitor_dict(
        self,
    ) -> Dict[str, _TraverseCallableType[Any]]:
        visitors = {}

        for name in dir(self):
            if name.startswith("visit_"):
                visitors[name[6:]] = getattr(self, name)
        return visitors

    @property
    def visitor_iterator(self) -> Iterator[ExternalTraversal]:
        """Iterate through this visitor and each 'chained' visitor."""

        v: Optional[ExternalTraversal] = self
        while v:
            yield v
            v = getattr(v, "_next", None)

    def chain(self: _ExtT, visitor: ExternalTraversal) -> _ExtT:
        """'Chain' an additional ExternalTraversal onto this ExternalTraversal

        The chained visitor will receive all visit events after this one.

        """
        tail = list(self.visitor_iterator)[-1]
        tail._next = visitor
        return self


class CloningExternalTraversal(ExternalTraversal):
    """Base class for visitor objects which can traverse using
    the :func:`.visitors.cloned_traverse` function.

    Direct usage of the :func:`.visitors.cloned_traverse` function is usually
    preferred.


    """

    __slots__ = ()

    def copy_and_process(
        self, list_: List[ExternallyTraversible]
    ) -> List[ExternallyTraversible]:
        """Apply cloned traversal to the given list of elements, and return
        the new list.

        """
        return [self.traverse(x) for x in list_]

    @overload
    def traverse(self, obj: Literal[None]) -> None: ...

    @overload
    def traverse(
        self, obj: ExternallyTraversible
    ) -> ExternallyTraversible: ...

    def traverse(
        self, obj: Optional[ExternallyTraversible]
    ) -> Optional[ExternallyTraversible]:
        """Traverse and visit the given expression structure."""

        return cloned_traverse(
            obj, self.__traverse_options__, self._visitor_dict
        )


class ReplacingExternalTraversal(CloningExternalTraversal):
    """Base class for visitor objects which can traverse using
    the :func:`.visitors.replacement_traverse` function.

    Direct usage of the :func:`.visitors.replacement_traverse` function is
    usually preferred.

    """

    __slots__ = ()

    def replace(
        self, elem: ExternallyTraversible
    ) -> Optional[ExternallyTraversible]:
        """Receive pre-copied elements during a cloning traversal.

        If the method returns a new element, the element is used
        instead of creating a simple copy of the element.  Traversal
        will halt on the newly returned element if it is re-encountered.
        """
        return None

    @overload
    def traverse(self, obj: Literal[None]) -> None: ...

    @overload
    def traverse(
        self, obj: ExternallyTraversible
    ) -> ExternallyTraversible: ...

    def traverse(
        self, obj: Optional[ExternallyTraversible]
    ) -> Optional[ExternallyTraversible]:
        """Traverse and visit the given expression structure."""

        def replace(
            element: ExternallyTraversible,
            **kw: Any,
        ) -> Optional[ExternallyTraversible]:
            for v in self.visitor_iterator:
                e = cast(ReplacingExternalTraversal, v).replace(element)
                if e is not None:
                    return e

            return None

        return replacement_traverse(obj, self.__traverse_options__, replace)


# backwards compatibility
Traversible = Visitable

ClauseVisitor = ExternalTraversal
CloningVisitor = CloningExternalTraversal
ReplacingCloningVisitor = ReplacingExternalTraversal


def iterate(
    obj: Optional[ExternallyTraversible],
    opts: Mapping[str, Any] = util.EMPTY_DICT,
) -> Iterator[ExternallyTraversible]:
    r"""Traverse the given expression structure, returning an iterator.

    Traversal is configured to be breadth-first.

    The central API feature used by the :func:`.visitors.iterate`
    function is the
    :meth:`_expression.ClauseElement.get_children` method of
    :class:`_expression.ClauseElement` objects.  This method should return all
    the :class:`_expression.ClauseElement` objects which are associated with a
    particular :class:`_expression.ClauseElement` object. For example, a
    :class:`.Case` structure will refer to a series of
    :class:`_expression.ColumnElement` objects within its "whens" and "else\_"
    member variables.

    :param obj: :class:`_expression.ClauseElement` structure to be traversed

    :param opts: dictionary of iteration options.   This dictionary is usually
     empty in modern usage.

    """
    if obj is None:
        return

    yield obj
    children = obj.get_children(**opts)

    if not children:
        return

    stack = deque([children])
    while stack:
        t_iterator = stack.popleft()
        for t in t_iterator:
            yield t
            stack.append(t.get_children(**opts))


@overload
def traverse_using(
    iterator: Iterable[ExternallyTraversible],
    obj: Literal[None],
    visitors: Mapping[str, _TraverseCallableType[Any]],
) -> None: ...


@overload
def traverse_using(
    iterator: Iterable[ExternallyTraversible],
    obj: ExternallyTraversible,
    visitors: Mapping[str, _TraverseCallableType[Any]],
) -> ExternallyTraversible: ...


def traverse_using(
    iterator: Iterable[ExternallyTraversible],
    obj: Optional[ExternallyTraversible],
    visitors: Mapping[str, _TraverseCallableType[Any]],
) -> Optional[ExternallyTraversible]:
    """Visit the given expression structure using the given iterator of
    objects.

    :func:`.visitors.traverse_using` is usually called internally as the result
    of the :func:`.visitors.traverse` function.

    :param iterator: an iterable or sequence which will yield
     :class:`_expression.ClauseElement`
     structures; the iterator is assumed to be the
     product of the :func:`.visitors.iterate` function.

    :param obj: the :class:`_expression.ClauseElement`
     that was used as the target of the
     :func:`.iterate` function.

    :param visitors: dictionary of visit functions.  See :func:`.traverse`
     for details on this dictionary.

    .. seealso::

        :func:`.traverse`


    """
    for target in iterator:
        meth = visitors.get(target.__visit_name__, None)
        if meth:
            meth(target)
    return obj


@overload
def traverse(
    obj: Literal[None],
    opts: Mapping[str, Any],
    visitors: Mapping[str, _TraverseCallableType[Any]],
) -> None: ...


@overload
def traverse(
    obj: ExternallyTraversible,
    opts: Mapping[str, Any],
    visitors: Mapping[str, _TraverseCallableType[Any]],
) -> ExternallyTraversible: ...


def traverse(
    obj: Optional[ExternallyTraversible],
    opts: Mapping[str, Any],
    visitors: Mapping[str, _TraverseCallableType[Any]],
) -> Optional[ExternallyTraversible]:
    """Traverse and visit the given expression structure using the default
    iterator.

     e.g.::

        from sqlalchemy.sql import visitors

        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,
    which does a breadth-first traversal using a stack.

    :param obj: :class:`_expression.ClauseElement` structure to be traversed

    :param opts: dictionary of iteration options.   This dictionary is usually
     empty in modern usage.

    :param visitors: dictionary of visit functions.   The dictionary should
     have strings as keys, each of which would correspond to the
     ``__visit_name__`` of a particular kind of SQL expression object, and
     callable functions  as values, each of which represents a visitor function
     for that kind of object.

    """
    return traverse_using(iterate(obj, opts), obj, visitors)


@overload
def cloned_traverse(
    obj: Literal[None],
    opts: Mapping[str, Any],
    visitors: Mapping[str, _TraverseCallableType[Any]],
) -> None: ...


# a bit of controversy here, as the clone of the lead element
# *could* in theory replace with an entirely different kind of element.
# however this is really not how cloned_traverse is ever used internally
# at least.
@overload
def cloned_traverse(
    obj: _ET,
    opts: Mapping[str, Any],
    visitors: Mapping[str, _TraverseCallableType[Any]],
) -> _ET: ...


def cloned_traverse(
    obj: Optional[ExternallyTraversible],
    opts: Mapping[str, Any],
    visitors: Mapping[str, _TraverseCallableType[Any]],
) -> Optional[ExternallyTraversible]:
    """Clone the given expression structure, allowing modifications by
    visitors for mutable objects.

    Traversal usage is the same as that of :func:`.visitors.traverse`.
    The visitor functions present in the ``visitors`` dictionary may also
    modify the internals of the given structure as the traversal proceeds.

    The :func:`.cloned_traverse` function does **not** provide objects that are
    part of the :class:`.Immutable` interface to the visit methods (this
    primarily includes :class:`.ColumnClause`, :class:`.Column`,
    :class:`.TableClause` and :class:`.Table` objects). As this traversal is
    only intended to allow in-place mutation of objects, :class:`.Immutable`
    objects are skipped. The :meth:`.Immutable._clone` method is still called
    on each object to allow for objects to replace themselves with a different
    object based on a clone of their sub-internals (e.g. a
    :class:`.ColumnClause` that clones its subquery to return a new
    :class:`.ColumnClause`).

    .. versionchanged:: 2.0  The :func:`.cloned_traverse` function omits
       objects that are part of the :class:`.Immutable` interface.

    The central API feature used by the :func:`.visitors.cloned_traverse`
    and :func:`.visitors.replacement_traverse` functions, in addition to the
    :meth:`_expression.ClauseElement.get_children`
    function that is used to achieve
    the iteration, is the :meth:`_expression.ClauseElement._copy_internals`
    method.
    For a :class:`_expression.ClauseElement`
    structure to support cloning and replacement
    traversals correctly, it needs to be able to pass a cloning function into
    its internal members in order to make copies of them.

    .. seealso::

        :func:`.visitors.traverse`

        :func:`.visitors.replacement_traverse`

    """

    cloned: Dict[int, ExternallyTraversible] = {}
    stop_on = set(opts.get("stop_on", []))

    def deferred_copy_internals(
        obj: ExternallyTraversible,
    ) -> ExternallyTraversible:
        return cloned_traverse(obj, opts, visitors)

    def clone(elem: ExternallyTraversible, **kw: Any) -> ExternallyTraversible:
        if elem in stop_on:
            return elem
        else:
            if id(elem) not in cloned:
                if "replace" in kw:
                    newelem = cast(
                        Optional[ExternallyTraversible], kw["replace"](elem)
                    )
                    if newelem is not None:
                        cloned[id(elem)] = newelem
                        return newelem

                # the _clone method for immutable normally returns "self".
                # however, the method is still allowed to return a
                # different object altogether; ColumnClause._clone() will
                # based on options clone the subquery to which it is associated
                # and return the new corresponding column.
                cloned[id(elem)] = newelem = elem._clone(clone=clone, **kw)
                newelem._copy_internals(clone=clone, **kw)

                # however, visit methods which are tasked with in-place
                # mutation of the object should not get access to the immutable
                # object.
                if not elem._is_immutable:
                    meth = visitors.get(newelem.__visit_name__, None)
                    if meth:
                        meth(newelem)
            return cloned[id(elem)]

    if obj is not None:
        obj = clone(
            obj, deferred_copy_internals=deferred_copy_internals, **opts
        )
    clone = None  # type: ignore[assignment]  # remove gc cycles
    return obj


@overload
def replacement_traverse(
    obj: Literal[None],
    opts: Mapping[str, Any],
    replace: _TraverseTransformCallableType[Any],
) -> None: ...


@overload
def replacement_traverse(
    obj: _CE,
    opts: Mapping[str, Any],
    replace: _TraverseTransformCallableType[Any],
) -> _CE: ...


@overload
def replacement_traverse(
    obj: ExternallyTraversible,
    opts: Mapping[str, Any],
    replace: _TraverseTransformCallableType[Any],
) -> ExternallyTraversible: ...


def replacement_traverse(
    obj: Optional[ExternallyTraversible],
    opts: Mapping[str, Any],
    replace: _TraverseTransformCallableType[Any],
) -> Optional[ExternallyTraversible]:
    """Clone the given expression structure, allowing element
    replacement by a given replacement function.

    This function is very similar to the :func:`.visitors.cloned_traverse`
    function, except instead of being passed a dictionary of visitors, all
    elements are unconditionally passed into the given replace function.
    The replace function then has the option to return an entirely new object
    which will replace the one given.  If it returns ``None``, then the object
    is kept in place.

    The difference in usage between :func:`.visitors.cloned_traverse` and
    :func:`.visitors.replacement_traverse` is that in the former case, an
    already-cloned object is passed to the visitor function, and the visitor
    function can then manipulate the internal state of the object.
    In the case of the latter, the visitor function should only return an
    entirely different object, or do nothing.

    The use case for :func:`.visitors.replacement_traverse` is that of
    replacing a FROM clause inside of a SQL structure with a different one,
    as is a common use case within the ORM.

    """

    cloned = {}
    stop_on = {id(x) for x in opts.get("stop_on", [])}

    def deferred_copy_internals(
        obj: ExternallyTraversible,
    ) -> ExternallyTraversible:
        return replacement_traverse(obj, opts, replace)

    def clone(elem: ExternallyTraversible, **kw: Any) -> ExternallyTraversible:
        if (
            id(elem) in stop_on
            or "no_replacement_traverse" in elem._annotations
        ):
            return elem
        else:
            newelem = replace(elem)
            if newelem is not None:
                stop_on.add(id(newelem))
                return newelem  # type: ignore
            else:
                # base "already seen" on id(), not hash, so that we don't
                # replace an Annotated element with its non-annotated one, and
                # vice versa
                id_elem = id(elem)
                if id_elem not in cloned:
                    if "replace" in kw:
                        newelem = kw["replace"](elem)
                        if newelem is not None:
                            cloned[id_elem] = newelem
                            return newelem  # type: ignore

                    cloned[id_elem] = newelem = elem._clone(**kw)
                    newelem._copy_internals(clone=clone, **kw)
                return cloned[id_elem]  # type: ignore

    if obj is not None:
        obj = clone(
            obj, deferred_copy_internals=deferred_copy_internals, **opts
        )
    clone = None  # type: ignore[assignment]  # remove gc cycles
    return obj