Как настроить повторы запросов с Tenacity: начните с конечной политики повторов. установите библиотеку командой pip install tenacity, повесьте на функцию декоратор @retry и задайте три параметра — stop для конечного числа попыток, wait для паузы между ними и retry для фильтра исключений. Ниже разобраны эти параметры, полный пример без сети и два контрольных теста.
Что разрешено повторять
Повтор — это повторный вызов операции после сбоя. Tenacity, по описанию в документации проекта, представляет собой библиотеку общего назначения для добавления поведения повторов к чему угодно. Практический вопрос в другом: какие сбои имеет смысл повторять, а какие приведут к лишней работе.
Документация Google Cloud Storage по стратегии повторов делит ответы на две группы. Транзиентные проблемы — коды HTTP 408, 429 и 5xx, а также таймауты сокета и разрывы TCP — обычно имеет смысл повторить. Постоянные ошибки указывают на то, что перед новой попыткой нужно изменить авторизацию или конфигурацию. Эта же страница перечисляет антипаттерны: повтор без паузы, безусловный повтор неидемпотентных операций, повтор неретраибельных ошибок, игнорирование лимитов и лишнее наслоение повторов.
Для Python-кода это означает: фильтр исключений задаёт, какие ошибки попадают в повтор. Библиотека даёт для этого набор предикатов. В справочнике API перечислены retry_if_exception, retry_if_exception_type, retry_if_not_exception_type, retry_unless_exception_type, retry_if_result, retry_if_not_result, retry_if_exception_message, retry_if_not_exception_message, retry_any и retry_all. Комбинировать условия можно оператором |, как показано в руководстве.
Отдельно стоит помнить про поведение по умолчанию. В документации Tenacity сказано, что базовый @retry без параметров повторяет вызов бесконечно и без ожидания при возникновении исключения. Такой режим годится для демонстрации и опасен в рабочем коде: он не даёт операции завершиться ошибкой. Поэтому первым делом задают stop.
Ещё одна граница проходит по смыслу операции. Разрешённый тип исключения описывает характер сбоя. Безопасность повторного бизнес-действия проверяется отдельно. Создание платежа, отправка письма или запись в очередь могут дать двойной эффект. Документация Google Cloud Storage формулирует это через идемпотентность: повтор запроса, который не идемпотентен, способен привести к гонкам и конфликтам. Поэтому перед настройкой повторов ответьте на вопрос, что произойдёт при повторном успешном выполнении операции.
Установка и декоратор
Установка занимает одну команду. Руководство Tenacity приводит её буквально: pip install tenacity. Отдельного сервиса, ключа или регистрации библиотека не требует — это пакет Python.
Дальше функция оборачивается декоратором. Следующие короткие фрагменты показывают форму API; полный исполняемый пример с определением TransientError приведён ниже.
from tenacity import retry
@retry
def do_something_unreliable():
...
В таком виде поведение будет бесконечным повтором без пауз. Практичная форма добавляет параметры:
from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_none
@retry(
stop=stop_after_attempt(3),
wait=wait_none(),
retry=retry_if_exception_type(TransientError),
reraise=True,
)
def work():
...
Каждый аргумент отвечает за своё. stop ограничивает число попыток. wait задаёт паузу перед следующей попыткой. retry определяет, какие исключения считаются поводом для повтора. reraise меняет то, какое исключение увидит вызывающий код после исчерпания попыток.
Справочник API описывает tenacity.retry как обёртку функции новым объектом Retrying: позиционные и именованные аргументы декоратора передаются этому объекту. Там же перечислены значения по умолчанию: stop — объект _stop_never, wait — wait_none, retry — retry_if_exception_type, reraise — False. Эти умолчания объясняют, почему голый декоратор повторяет бесконечно: условие остановки по умолчанию не наступает никогда.
Декоратор можно применять и к корутинам. В руководстве сказано, что retry работает с корутинами asyncio и Tornado версии 4.5 и выше, а паузы выполняются асинхронно. Для этого есть и отдельный контроллер AsyncRetrying, описанный в справочнике API. Если функция объявлена через async def, декоратор ставится над ней обычным способом.
Порядок декораторов имеет значение. В исходниках LangChain для повторяемых Runnable видно, что повтор ограничен конкретным узлом цепочки: в комментарии к коду прямо сказано, что область повтора держат как можно меньше и повторяют тот Runnable, который вероятнее всего упадёт. Тот же принцип работает с обычными функциями: оборачивайте минимальный участок, который действительно может дать транзиентный сбой.
Stop wait retry reraise
Четыре параметра декоратора образуют ядро политики. Разберём каждый по отдельности, опираясь на руководство и справочник API Tenacity.
Stop. stop_after_attempt(max_attempt_number) останавливает работу, когда номер предыдущей попытки достиг максимума. Важная деталь: stop_after_attempt(3) означает три попытки всего, включая первую. Есть и ограничение по времени: stop_after_delay(max_delay) останавливает, когда время с первой попытки превысило лимит. Условия объединяются оператором |; в руководстве приведён пример stop_after_delay(10) | stop_after_attempt(5), который завершает работу по любому из двух событий. В справочнике есть также stop_all, stop_any и stop_when_event_set.
Wait. wait_fixed(2) выдерживает фиксированную паузу. wait_random(min=1, max=2) выбирает случайную паузу в диапазоне. wait_exponential(multiplier=1, min=4, max=10) даёт экспоненциальный рост с нижней и верхней границей. wait_none() не ждёт вовсе. Справочник API отдельно предупреждает: у wait_exponential интервалы фиксированные, без дрожания, поэтому стратегия подходит для ожидания недоступного ресурса и не подходит для разрешения конкуренции между процессами за общий ресурс — для второго случая предлагается wait_random_exponential.
Retry. Предикат решает, продолжать ли повторы. retry_if_exception_type(IOError) повторяет только при указанном типе исключения и немедленно поднимает остальные. retry_if_not_exception_type(ClientError) работает наоборот: повторяет при любом исключении, кроме перечисленных. retry_if_result(is_none_p) смотрит на возвращённое значение: в руководстве показан пример, где повтор запускается, если функция вернула None. Условия тоже комбинируются оператором |.
Reraise. По умолчанию, когда функция исчерпала попытки, поднимается RetryError, а исходное исключение оказывается в середине трассировки. Параметр reraise=True меняет картину: исключение вашего кода оказывается в конце трассировки, там, где его видно. В руководстве это описано прямо и сопровождается примером с stop_after_attempt(3).
Есть и способ попросить повтор вручную. Руководство упоминает исключение TryAgain: его можно поднять внутри функции в любой момент, чтобы запустить новую попытку независимо от предиката. Это удобно, когда результат получен, но по бизнес-правилу его нужно перезапросить.
Сводка параметров:
| Параметр | Что задаёт | Пример из документации | Поведение по умолчанию |
|---|---|---|---|
stop |
Когда прекратить попытки | stop_after_attempt(3), stop_after_delay(10) |
_stop_never — повторы бесконечны |
wait |
Паузу перед следующей попыткой | wait_fixed(2), wait_random(1, 2) |
wait_none — без паузы |
retry |
Какие сбои повторять | retry_if_exception_type(IOError) |
retry_if_exception_type |
reraise |
Какое исключение увидит вызывающий | reraise=True |
False — поднимается RetryError |
Полный пример без сети
Ниже — учебный пример, который не обращается к сети и не вызывает платных API. Он показывает политику целиком: конечное число попыток, фильтр исключений, отсутствие паузы для скорости теста и проброс исходного исключения.
from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_none
class TransientError(Exception):
pass
calls = 0
@retry(stop=stop_after_attempt(3), wait=wait_none(),
retry=retry_if_exception_type(TransientError), reraise=True)
def work():
global calls
calls += 1
if calls < 3:
raise TransientError("temporary")
return "ok"
assert work() == "ok"
assert calls == 3
Разберём, что здесь происходит. Функция work при первых двух вызовах поднимает TransientError, на третьем возвращает строку. Декоратор видит тип исключения, сверяет его с retry_if_exception_type(TransientError) и запускает новую попытку. Счётчик calls увеличивается на каждой попытке, поэтому после успеха он равен трём. wait_none() выбран только для локального теста: ждать в проверке нечего. В рабочем коде для сетевых операций выбирают backoff, дрожание и верхний предел, подобранный под задачу.
Этот пример — учебная конструкция. Он не измеряет производительность библиотеки и не подтверждает настройки какого-либо провайдера. Его задача — дать проверяемую политику, которую можно прогнать локально и увидеть, как параметры влияют на число вызовов.
Полезно сразу добавить наблюдаемость. В руководстве Tenacity описаны колбэки before, after и before_sleep, а также готовые функции before_log, after_log и before_sleep_log, принимающие логгер и уровень. Отдельно упомянут before_sleep: он вызывается только перед паузой, то есть логирует те сбои, которые действительно будут повторены. Ещё есть атрибут statistics у обёрнутой функции — в руководстве показано, как после серии неудач вывести raise_my_exception.retry.statistics. Для отладки политики это дешевле, чем добавлять собственные счётчики.
Два контрольных теста
Политику повторов стоит проверить на двух сценариях, которые ловят самые частые ошибки настройки. Оба выполняются локально и не требуют сети.
Тест первый: исключение вне фильтра. Замените в примере поднимаемое исключение на ValueError. Этот тип не входит в TransientError, поэтому предикат retry_if_exception_type(TransientError) не даст согласия на повтор. Ожидаемый результат: одна попытка и ValueError наружу. Если повторы всё равно происходят, значит фильтр задан слишком широко — например, стоит retry_if_exception_type(Exception) или retry_any с лишним условием. Такой тест показывает, что политика действительно ограничивает круг повторяемых сбоев.
Тест второй: исчерпание попыток. Сделайте так, чтобы функция всегда поднимала TransientError. Ожидаемый результат: ровно три попытки, после чего наружу уходит последнее исключение благодаря reraise=True. Если вы уберёте reraise=True, наружу пойдёт RetryError, а исходное исключение окажется в середине трассировки — именно так это описано в руководстве Tenacity. Второй тест проверяет сразу две вещи: что stop действительно останавливает работу и что вызывающий код получает ожидаемый тип ошибки.
Оба теста можно дописать после основного примера. Каждый начинает собственный счётчик:
control_calls = 0
@retry(stop=stop_after_attempt(3), wait=wait_none(),
retry=retry_if_exception_type(TransientError), reraise=True)
def outside_filter():
global control_calls
control_calls += 1
raise ValueError("not transient")
try:
outside_filter()
except ValueError:
pass
else:
raise AssertionError("ValueError expected")
assert control_calls == 1
control_calls = 0
@retry(stop=stop_after_attempt(3), wait=wait_none(),
retry=retry_if_exception_type(TransientError), reraise=True)
def exhausted():
global control_calls
control_calls += 1
raise TransientError("still temporary")
try:
exhausted()
except TransientError:
pass
else:
raise AssertionError("TransientError expected")
assert control_calls == 3
Это такие же обычные утверждения, как в примере выше. Счётчик вызовов даёт точную проверку числа попыток, а тип пойманного исключения — проверку фильтра и reraise. Такой набор ловит ошибку, при которой политика выглядит настроенной, но на деле повторяет всё подряд или не останавливается.
Дополнительно проверьте комбинацию условий остановки. Если вы задали stop_after_delay(10) | stop_after_attempt(5), убедитесь, что при быстрых сбоях срабатывает счётчик попыток, а при медленных — лимит времени. В руководстве этот оператор описан как объединение нескольких условий остановки, и проверка каждого плеча отдельно избавляет от сюрпризов в проде.
Backoff jitter и лимит времени
Экспоненциальный backoff увеличивает паузу между попытками. В справочнике API wait_exponential принимает множитель, минимум и максимум, а также основание степени. Пример из руководства — wait_exponential(multiplier=1, min=4, max=10) — начинает с четырёх секунд, растёт по степеням двойки и упирается в десять секунд.
Дрожание (jitter) добавляет к паузе случайную составляющую. Это важно, когда много клиентов одновременно получают отказ и одновременно же повторяют запрос. Руководство Tenacity прямо связывает дрожание с задачей избежать «стада» одновременных повторов. Для этого есть wait_random(min, max) и wait_random_exponential(multiplier, max). Второй вариант описан в справочнике как стратегия для распределённых систем, где несколько нескоординированных процессов конкурируют за общий ресурс; там же указано, что она соответствует алгоритму «Full Jitter».
Комбинировать паузы можно сложением и цепочкой. В руководстве приведён пример wait_fixed(3) + wait_random(0, 2): минимум три секунды плюс случайная добавка до двух. Есть и wait_chain, который задаёт разные паузы для разных этапов: например, три секунды для первых трёх попыток, семь секунд для следующих двух и девять секунд дальше. Справочник API описывает wait_chain так: когда стратегии исчерпаны, дальше используется последняя из них.
Условия stop проверяются между попытками и сами не прерывают зависший сетевой вызов. Для него нужен timeout клиента. Лимит повторов по времени задаётся двумя способами. Первый — stop_after_delay, который останавливает повторы по общему времени с первой попытки. Второй — комбинация с ограничением числа попыток через оператор |. Документация Google Cloud Storage показывает, как это выглядит в клиентских библиотеках: у Java по умолчанию шесть попыток, начальная задержка одна секунда, множитель 2.0, максимальная задержка 32 секунды и общий таймаут 50 секунд; у Python начальная задержка одна секунда, множитель 2, максимальная задержка 60 секунд и общий дедлайн 120 секунд. Это настройки названных клиентских библиотек. Для своей задачи политику выбирают отдельно.
Для OpenAI API официальный кулинарный справочник приводит пример с Tenacity: декоратор с wait_random_exponential(min=1, max=60) и stop_after_attempt(6). Там же отмечено, что неуспешные запросы тоже расходуют лимит запросов в минуту, поэтому бесконечно пересылать один и тот же запрос бессмысленно. Для пакетной обработки тот же материал советует добавлять упреждающую задержку, рассчитанную от лимита: при 20 запросах в минуту задержка между запросами составит от трёх до шести секунд.
| Стратегия ожидания | Характер паузы | Когда подходит |
|---|---|---|
wait_none |
Без паузы | Локальные тесты |
wait_fixed |
Одинаковая пауза | Простые сценарии с известным интервалом |
wait_random |
Случайная в диапазоне | Разброс одновременных повторов |
wait_exponential |
Рост с верхней границей | Ожидание недоступного ресурса |
wait_random_exponential |
Рост со случайным окном | Конкуренция процессов за общий ресурс |
wait_chain |
Разные паузы по этапам | Постепенное увеличение интервалов |
Идемпотентность и слои retry
Повтор безопасен тогда, когда операцию можно выполнить несколько раз с тем же конечным состоянием. Документация Google Cloud Storage определяет идемпотентность именно так: запрос можно выполнять повторно, не меняя итоговое состояние целевого ресурса. Там же приведена классификация операций: все запросы на чтение и список всегда идемпотентны, создание уведомления Pub/Sub — никогда, а часть операций условно идемпотентна и безопасна для повтора только при наличии определённых предусловий, таких как ifGenerationMatch или etag.
Практический вывод для Python-кода: тип исключения и идемпотентность действия — два независимых вопроса. Разрешив повтор для TransientError, вы разрешили его для всех операций, которые её поднимают. Если среди них есть создание сущности без ключа идемпотентности, повтор может создать дубль. Документация Google Cloud Storage относит безусловный повтор неидемпотентных операций к антипаттернам и советует либо обеспечить обработку дублей, либо отказаться от повтора.
Второй слой проблемы — вложенные повторы. Многие SDK уже содержат собственный механизм повторов. В исходниках OpenAI-клиента, приведённых в кулинарном справочнике, видны внутренние методы _should_retry и _retry_request, которые повторяют запрос до того, как исключение дойдёт до вашего кода. Документация Google Cloud Storage описывает тот же эффект числами: если приложение повторяет операцию три раза, а клиентская библиотека внутри повторяет каждый такой вызов ещё трижды, суммарно получается девять попыток. Страница называет это антипаттерном «лишнее наслоение повторов» и советует либо использовать встроенные механизмы, либо явно ограничить повторы на одном из уровней.
Отсюда рабочее правило: считайте общую границу попыток вместе с тем, что делает SDK. Если клиент уже повторяет запросы, ваш декоратор добавляет множитель к числу обращений. Полезно выяснить поведение библиотеки до того, как настраивать внешний слой.
Третий момент — неопределённый исход. Таймаут после того, как внешнее действие уже могло выполниться, означает, что результат неизвестен. Повтор в такой ситуации может привести к двойному эффекту, если операция не идемпотентна. Документация Google Cloud Storage советует для неидемпотентных операций либо предусловия, либо отказ от повтора.
Наконец, область повтора. В исходниках LangChain для повторяемых Runnable есть явная рекомендация держать область повтора как можно меньше и оборачивать только тот узел, который вероятнее всего упадёт. Тот же принцип применим к обычному коду: ограничьте область повтора конкретным сетевым вызовом. Повтор всей функции обработки заказа способен затронуть уже завершённые действия. Тогда повтор не перезапустит уже выполненные шаги.
Частые вопросы
Как настроить повторы запросов с Tenacity в Python?
Установите пакет командой pip install tenacity, затем повесьте на функцию декоратор @retry и передайте ему stop, wait и retry. Без этих параметров декоратор повторяет вызов бесконечно и без паузы, поэтому конечное условие остановки задают первым делом. Минимальный рабочий набор — stop_after_attempt(3), подходящая стратегия ожидания и предикат по типу исключения.
Чем stop_after_attempt(3) отличается от трёх повторов?
stop_after_attempt(3) означает три попытки всего, включая первую. Три повтора после первой дали бы четыре вызова. Это различие важно при расчёте нагрузки: при отсутствии вложенных повторов число вызовов ограничено значением stop_after_attempt. Встроенные повторы SDK учитываются дополнительно.
Что делает reraise=True?
По умолчанию после исчерпания попыток поднимается RetryError, а исходное исключение оказывается в середине трассировки. Параметр reraise=True помещает исключение вашего кода в конец трассировки, где его видно. Вызывающий код в этом случае ловит то же исключение, что подняла функция.
Как работает retry_if_exception_type?
Это предикат, который даёт согласие на повтор только для перечисленных типов исключений. Все остальные типы поднимаются немедленно, без дополнительных попыток. В справочнике API перечислены и родственные предикаты: retry_if_not_exception_type, retry_unless_exception_type, retry_if_result, retry_if_exception_message, а также комбинаторы retry_any и retry_all.
Как Tenacity работает с асинхронным кодом?
Декоратор retry применяется к корутинам asyncio и Tornado версии 4.5 и выше, а паузы выполняются асинхронно. Для явного управления есть контроллер AsyncRetrying, описанный в справочнике API. Он поддерживает те же стратегии остановки, ожидания и предикаты, что и синхронный Retrying.
