From 0be95b1996c6cf75472193cb074ac38e5a0f4e8b Mon Sep 17 00:00:00 2001 From: Julien Danjou Date: Tue, 24 Feb 2026 17:52:30 +0100 Subject: [PATCH] docs: document generator limitations and argument caveats Fixes #64 Fixes #66 Fixes #138 Document that @retry does not support generator functions, and that generators passed as arguments to retried functions will be exhausted after the first attempt. Include a workaround using factory functions. Co-Authored-By: Claude Opus 4.6 Change-Id: I4fe3ba2d82d1204a7f583b054064999dc1720a03 --- doc/source/index.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/doc/source/index.rst b/doc/source/index.rst index e9c8c199..ba21fd93 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -733,6 +733,37 @@ You can use alternative event loops by passing the correct sleep function: async def my_async_trio_function_with_sleep(): ... +Generators +~~~~~~~~~~ + +``retry`` does not support generator or async generator functions. Decorating a +generator with ``@retry`` will not retry on exceptions raised during iteration +— the decorator wraps the function call itself, which for generators simply +returns a generator object without executing any of the body. + +Also note that generators passed *as arguments* to a retried function will be +exhausted after the first attempt and will not be rewound automatically on +retry. If you need to pass a generator as an argument, consider passing a +factory function instead: + +.. code-block:: python + + # Bad: generator will be exhausted after the first attempt + @retry + def process(items): + for item in items: + do_work(item) + + process(my_generator()) # retries will see an empty generator + + # Good: pass a factory so a fresh generator is created on each attempt + @retry + def process(items_factory): + for item in items_factory(): + do_work(item) + + process(my_generator) # each retry gets a fresh generator + Contribute ----------