Currently, the Custom Callbacks section is a bit brief. For example, user might want to know when will before and after be invoked, and will they be invoked before or after before_sleep.
So, I would propose adding a flow chart displaying the sequence of the functions, or add example results to help readers better understanding.
For example, here is a code snippet showing when will the function be invoked and what effect will their return values will have.
```python
from typing import Callable
from tenacity import (
retry,
retry_if_exception_type,
stop_after_attempt,
)
def construct_function(name: str, *, ret=None, base_function=None) -> Callable:
# log funciton invoking
def func(*args, **kwargs):
print(name.ljust(10), str(args).ljust(10), str(kwargs).ljust(10))
if base_function is not None:
return base_function(*args, **kwargs)
else:
return ret
return func
counter = 0
wrapper = retry(
sleep=construct_function("sleep"),
stop=construct_function("stop", base_function=stop_after_attempt(3)),
wait=construct_function("wait", ret=2.34),
# retry=construct_function("retry", ),
retry=retry_if_exception_type(),
before=construct_function("before"),
after=construct_function("after"),
before_sleep=construct_function("before_sleep"),
retry_error_callback=construct_function("retry_error_callback"),
)
@wrapper
def success():
global counter
print(f"* main, {counter=}")
if counter < 2:
# success after 2 failed attempts
counter += 1
raise RuntimeError
@wrapper
def fail():
raise ValueError
success()
print("\n=======\n")
fail()
```
Output:
```plaintext
before (,) {}
* main, counter=0
after (,) {}
stop (,) {}
wait (,) {}
before_sleep (,) {}
sleep (2.34,) {}
before (,) {}
* main, counter=1
after (,) {}
stop (,) {}
wait (,) {}
before_sleep (,) {}
sleep (2.34,) {}
before (,) {}
* main, counter=2
=======
before (,) {}
after (,) {}
stop (,) {}
wait (,) {}
before_sleep (,) {}
sleep (2.34,) {}
before (,) {}
after (,) {}
stop (,) {}
wait (,) {}
before_sleep (,) {}
sleep (2.34,) {}
before (,) {}
after (,) {}
stop (,) {}
retry_error_callback (,) {}
```
Currently, the Custom Callbacks section is a bit brief. For example, user might want to know when will
beforeandafterbe invoked, and will they be invoked before or afterbefore_sleep. So, I would propose adding a flow chart displaying the sequence of the functions, or add example results to help readers better understanding. For example, here is a code snippet showing when will the function be invoked and what effect will their return values will have.