degenbot.pathfinding
====================

.. py:module:: degenbot.pathfinding

.. autoapi-nested-parse::

   Pathfinding utilities for discovering arbitrage routes.

   Barrier module (ADR-013: the Pydantic barrier): bridges the Rust
   ``build_path_graph`` / ``find_paths_rust`` seams from ``_ffi`` and re-exports
   the deep pathfinding logic from :mod:`._pathfinding`. Importers should use::

       from degenbot.pathfinding import find_paths, find_paths_async

   rather than reaching into ``degenbot._ffi`` directly.







Package Contents
----------------

.. py:class:: PathfindingRequest

   Search parameters shared by `find_paths` and `find_paths_async`.

   Fields:
       chain_id: Chain ID restricting pool and token queries.
       start_tokens: Token addresses that begin a path.
       end_tokens: Token addresses that end a path.
       database_path: File-backed SQLite database opened by Rust read seams.
       min_depth: Minimum hops in yielded paths.
       max_depth: Optional maximum hops in yielded paths.
       pool_types: Typed pool families to include (default V2/V3/V4).
       pool_type_per_depth: Optional per-depth allowed pool-family sets; a
           ``None`` entry allows all kinds at that depth.
       allowed_intermediate_tokens: Optional intermediate-token whitelist.



   .. py:attribute:: chain_id
      :type:  int


   .. py:attribute:: start_tokens
      :type:  collections.abc.Iterable[degenbot.types.chain.ChecksummedAddress | str]


   .. py:attribute:: end_tokens
      :type:  collections.abc.Iterable[degenbot.types.chain.ChecksummedAddress | str]


   .. py:attribute:: database_path
      :type:  pathlib.Path


   .. py:attribute:: min_depth
      :type:  int
      :value: 2



   .. py:attribute:: max_depth
      :type:  int | None
      :value: None



   .. py:attribute:: pool_types
      :type:  collections.abc.Sequence[degenbot.pathfinding.PoolKind]


   .. py:attribute:: pool_type_per_depth
      :type:  collections.abc.Sequence[set[degenbot.pathfinding.PoolKind] | None] | None
      :value: None



   .. py:attribute:: allowed_intermediate_tokens
      :type:  collections.abc.Iterable[degenbot.types.chain.ChecksummedAddress | str] | None
      :value: None



.. py:class:: PathStep

   PathStep class.


   .. py:attribute:: address
      :type:  degenbot.types.chain.ChecksummedAddress


   .. py:attribute:: type
      :type:  degenbot.pathfinding.PoolKind


   .. py:attribute:: hash
      :type:  str | None
      :value: None



.. py:function:: find_paths(*, request: PathfindingRequest) -> collections.abc.Iterator[collections.abc.Sequence[PathStep]]

   Find paths from each start token to each end token via the Rust DFS.

   :param request: The graph scope + traversal constraints for this search.

   :Yields: A valid arbitrage path from a start token to an end token.


.. py:function:: find_paths_async(*, request: PathfindingRequest, batch_size: int = 1000, prepare_traversals: collections.abc.Callable[..., list[_Traversal]] = _prepare_traversals, find_paths_async_rust: collections.abc.Callable[..., Any] = find_paths_async_rust) -> collections.abc.AsyncGenerator[collections.abc.Sequence[PathStep], None]
   :async:


   Async `find_paths`, driving the Rust batched async iterator.

   The one-time prep runs on the shared tokio blocking pool, so neither the
   database resolution nor the Rust bulk read stalls the event loop.

   :param request: The graph scope + traversal constraints for this search.
   :param batch_size: Paths per Rust delivery batch (default 1000), clamped `>= 1`.
   :param prepare_traversals: The one-time prep seam called as
                              ``prepare_traversals(request=request)`` on the blocking pool.
   :param find_paths_async_rust: The Rust batched async iterator factory, called
                                 with the traversal's positional seam arguments.

   :Yields: Sequences of PathStep objects representing arbitrage paths.

   :raises The producer's exception, re-raised at the consumer.: