NanoWait 7.2

Esperas previsíveis e retries resilientes para automação Python.

O NanoWait reúne espera adaptativa, polling de condições e execução com retentativas em uma API pequena. A versão 7.2 acrescenta backoff exponencial, jitter e limite de intervalo ao executor execute(). Esses recursos reduzem rajadas de requisições quando uma API, conexão ou serviço externo oscila.

Instalação

pip install nano-wait

Para desenvolvimento:

pip install nano-wait[dev]

O suporte opcional à leitura de sinal Wi-Fi continua disponível em plataformas compatíveis:

pip install nano-wait[wifi]

Uso rápido

from nano_wait import wait, wait_until

wait(2)                         # nunca fica abaixo de 2 segundos
wait(2, smart=True)             # pode ser menor quando for apenas uma cortesia
wait(lambda: page.is_loaded(), timeout=10)
wait_until(
    lambda: api_is_ready(),
    timeout=15,
    msg="A API não ficou pronta",
)

Retry para rede instável

Use execute() quando uma operação pode falhar temporariamente. Por padrão, o intervalo cresce após cada falha, recebe uma pequena variação aleatória e não ultrapassa max_interval.

import requests
from nano_wait import execute

result = execute(
    lambda: requests.get(url, timeout=3).json(),
    timeout=30,
    interval=0.5,
    backoff=2.0,
    max_interval=8.0,
    jitter=0.20,
    max_attempts=8,
    expected_exceptions=(requests.RequestException,),
)

if result.success:
    payload = result.result
else:
    result.raise_if_failed()

A sequência de espera do exemplo cresce aproximadamente como 0.5s, 1s, 2s, 4s e 8s. O jitter evita que várias instâncias que falharam juntas repitam simultaneamente. O timeout é total e inclui a execução da função e os intervalos entre tentativas.

Parâmetros de execute

Retornos truthy e o valor 0 representam sucesso. Outros retornos falsy geram nova tentativa. Exceções que não pertençam a expected_exceptions não são escondidas.

Espera síncrona

from nano_wait import wait

wait(1.5)
wait(1.5, speed="fast")
wait(1.5, profile="safe")
report = wait(1.5, explain=True)

No modo padrão (smart=False), wait(t) preserva um piso real de t segundos. O sistema pode aumentar a espera quando estiver sobrecarregado. No modo smart=True, a espera pode ser reduzida quando o sistema estiver saudável.

Espera assíncrona

import asyncio
from nano_wait import wait_async

async def main():
    await wait_async(1, smart=True)
    await wait_async(lambda: check_ready(), timeout=10)

asyncio.run(main())

A função assíncrona usa asyncio.sleep() e executa condições síncronas em uma thread para não bloquear o event loop.

Polling e timeout

from nano_wait import wait_until, WaitTimeoutError

try:
    wait_until(
        lambda: driver.title == "Home",
        timeout=15,
        msg="A página Home não carregou",
    )
except WaitTimeoutError as error:
    print(error)

wait(condition) retorna True quando a condição é satisfeita e False quando o timeout termina. Com raise_on_timeout=True, ele lança WaitTimeoutError.

Decorator de retry

O decorator usa o mesmo motor resiliente de execute().

from nano_wait import retry

@retry(
    timeout=30,
    interval=0.5,
    backoff=2,
    max_attempts=6,
    max_interval=10,
    jitter=0.15,
)
def fetch_data():
    return client.fetch()

result = fetch_data()
if result.success:
    print(result.result)

O decorator retorna ExecutionResult, permitindo consultar success, result, attempts, duration e error.

Perfis

wait(2, profile="safe")
execute(fetch_data, profile="safe", timeout=30)

Utilitários de rede

from nano_wait import has_internet

if has_internet(timeout=1):
    execute(fetch_data, timeout=20)
else:
    wait(2, profile="safe")

has_internet() faz uma tentativa simples de conexão TCP. Ela é um diagnóstico pontual, não uma garantia de que uma API específica esteja disponível. Para a operação real, prefira execute() com expected_exceptions restrito às exceções de rede da biblioteca cliente.

Aprendizado e telemetria

O NanoWait mantém um ajuste de aprendizado por perfil em ~/.nano_wait_learning.json. Esse ajuste influencia esperas adaptativas, mas não remove o piso de wait(t) no modo padrão. Telemetria e explicações podem ser ativadas pelas opções da API.

Migração da versão 7.1

Nenhuma chamada existente precisa ser alterada. O comportamento anterior de execute() continua disponível com interval, timeout, max_attempts, on_error e expected_exceptions. Para aproveitar a melhoria, adicione backoff, max_interval e jitter.

A versão também corrige um caso em que o aprendizado acumulado ou um perfil agressivo podia fazer wait(t) ficar abaixo do valor solicitado apesar da garantia documentada.

Desenvolvimento e testes

pytest -q

A versão 7.2 inclui testes para crescimento de backoff, jitter configurável, limite de tentativas, validação de parâmetros e propagação de exceções inesperadas.

Licença

Este projeto é distribuído sob a licença MIT. Consulte LICENSE.