degenbot.bot_lifecycle
======================

.. py:module:: degenbot.bot_lifecycle

.. autoapi-nested-parse::

   Shared Python-handle teardown for ``Bot``.

   ``Bot`` is the single-chain facade (ADR-006 D5) with attribute shape
   (``_trackers``, ``pools``, ``tokens``, ``managed_pools``, ``_py_bot``,
   ``_provider``, ``_io``). This module holds the teardown body in one place so
   the facade delegates to it rather than inlining ~15 lines.

   Two entry points:

   - :func:`release_python_state` — the *mid-lifecycle* handshake: drop
     tracker caches/snapshots + pool/token registries once the Rust engine has
     taken ownership of canonical pool state. The Bot keeps running; only the
     redundant Python caches go.
   - :func:`close` — the *end-of-life* teardown: composes
     :func:`release_python_state`, closes the provider, and drops references. Idempotent
     via a per-instance ``_closed`` flag.

   The Rust ``Bot`` is reference-counted; closing a Python wrapper only drops
   that wrapper's ref. A running engine that took its own ref (via
   ``EngineRegistry(bot=bot)`` → ``ArbitrageEngine(py_bot=...)``) is unaffected.





Module Contents
---------------

.. py:function:: release_python_state(bot: _BotLike) -> None

   Drop Python-side pool/token/tracker caches once Rust owns canonical state.

   Clears every tracker's ``_tracked_pools``/``_untracked_pools``, calls
   ``unload_snapshot()`` where present, then resets the pool and token
   registries. Idempotent and safe to call before :func:`close`.


.. py:function:: close(bot: _BotLike) -> None

   End-of-life teardown: release state, remove DB session, close provider, drop refs.

   Idempotent — safe to call directly and again from a context manager's
   ``__exit__``/``__aexit__``. Composes :func:`release_python_state`, so it
   is also safe after an explicit mid-lifecycle ``release_python_state`` call.