From 3cd900966465891a24f1c49e0882129ceb2a9725 Mon Sep 17 00:00:00 2001 From: Julien Danjou Date: Fri, 20 Feb 2026 13:45:11 +0100 Subject: [PATCH] docs: document RetryCallState attributes including seconds_since_start MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add an attribute reference for RetryCallState in the docs, listing attempt_number, outcome, seconds_since_start, idle_for, and start_time. Includes a short example showing how to log total elapsed time via the after callback — directly addressing the common confusion between seconds_since_start (wall-clock elapsed) and idle_for (sleep time only). Closes #303 Co-Authored-By: Claude Sonnet 4.6 Change-Id: I1dbaa9072c2f47822e05f859514a42dcf83ae6d3 --- doc/source/index.rst | 29 +++++++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/doc/source/index.rst b/doc/source/index.rst index 8ad7e53e..bcb02bbb 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -416,6 +416,35 @@ RetryCallState ~~~~~~~~~~~~~~ ``retry_state`` argument is an object of :class:`~tenacity.RetryCallState` class. +Its most useful attributes are: + +* ``attempt_number`` — number of the current attempt (starts at 1) +* ``outcome`` — a :class:`concurrent.futures.Future` holding the last result or exception +* ``seconds_since_start`` — total elapsed seconds from the first attempt to the last outcome (``None`` if no outcome yet) +* ``idle_for`` — cumulative seconds spent sleeping between attempts +* ``start_time`` — :func:`time.monotonic` timestamp of the first attempt + +For example, to log the total elapsed time after all retries: + +.. testcode:: + + import logging + + logging.basicConfig(stream=sys.stderr, level=logging.DEBUG) + + logger = logging.getLogger(__name__) + + def log_elapsed(retry_state): + logger.info('Finished after %.3fs', retry_state.seconds_since_start) + + @retry(stop=stop_after_attempt(3), after=log_elapsed) + def raise_my_exception(): + raise MyException("Fail") + + try: + raise_my_exception() + except RetryError: + pass Other Custom Callbacks ~~~~~~~~~~~~~~~~~~~~~~