NanoWait v7 — Adaptive Execution Engine for Python

Stop waiting blindly. Execute intelligently.

NanoWait substitui time.sleep() por um motor adaptativo que observa CPU e RAM em tempo real e aprende com cada execução.

⚡ Instalação

pip install nano-wait

Suporte a Wi-Fi (Windows):

pip install nano-wait[wifi]

🚀 Uso em 30 segundos

from nano_wait import wait

# Espera padrão: nunca entrega menos do que o pedido
# Se o sistema estiver lento, aguarda um pouco mais
wait(2)

# Modo smart: pode reduzir em sistemas ociosos e rápidos
wait(2, smart=True)

# Polling até condição ser True (ou timeout)
wait(lambda: button.is_visible(), timeout=10)

# Condição com erro customizado
from nano_wait import wait_until
wait_until(lambda: page.is_loaded(), timeout=10, msg="Página não carregou")

🧰 API Completa

wait(t, **kwargs) — O coração da lib

Presets de velocidade: "crawl" | "slow" | "normal" | "fast" | "ultra" | "turbo"

wait(1, speed="fast")       # espera rápida
wait(1, speed=4.5)          # fator personalizado
wait(1, profile="ci")       # perfil CI/CD (agressivo)
wait(1, explain=True)       # retorna ExplainReport

wait_until(condition, *, timeout, msg, **kwargs) — Polling semântico

Igual ao wait(callable) mas lança WaitTimeoutError com mensagem customizável.

from nano_wait import wait_until, WaitTimeoutError

try:
    wait_until(lambda: driver.title == "Home", timeout=15, msg="Home page não carregou")
except WaitTimeoutError as e:
    print(f"Falhou: {e}")

timed_wait(label) — Context manager de medição

from nano_wait import timed_wait

with timed_wait("login_flow") as info:
    driver.find_element("#user").send_keys("admin")
    driver.find_element("#pass").send_keys("pass")
    driver.find_element("#submit").click()

print(f"Login levou {info['duration']:.3f}s")

execute(fn, **kwargs) — Execução com retry inteligente

from nano_wait import execute

result = execute(
    lambda: api.get_user(42),
    timeout=10,
    interval=0.3,
    max_attempts=5,
    on_error=lambda e, n: print(f"Tentativa {n}: {e}"),
)

if result.success:
    print(result.result)
else:
    result.raise_if_failed()  # relança a última exceção

wait_async — Versão assíncrona

import asyncio
from nano_wait import wait_async

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

asyncio.run(main())

wait_pool — Múltiplos waits em paralelo

from nano_wait import wait_pool

# Dispara 3 esperas simultaneamente
results = wait_pool([1.0, 2.0, 0.5], speed="fast")

🎛️ Perfis de Execução

wait(2, profile="turbo")   # o mais rápido possível
wait(2, profile="safe")    # o mais estável possível

🔁 Decorators

from nano_wait import retry, timed, wait_before

# Retry automático até sucesso
@retry(timeout=10, max_attempts=5, smart=True)
def fetch_data():
    return requests.get(url).json()

# Mede tempo de execução
@timed()
def process_image(img):
    ...

# Espera adaptativa antes de cada chamada
@wait_before(0.5, smart=True)
def click_button(driver, selector):
    driver.find_element(selector).click()

🧠 Como o motor pensa

NanoWait tem dois modos de operação:

Modo padrão (smart=False) — previsível, seguro para testes:

WaitTime = BaseTime × (1 + overload_penalty) × ProfileAggressiveness

• overload_penalty só entra quando o sistema está sobrecarregado (CPU/RAM acima do limiar)
• wait(2) nunca devolve menos de 2s — garante que seus testes não ficam flaky

Modo smart (smart=True) — adaptativo, ideal para automação:

WaitTime = (BaseTime / (SystemHealth × SpeedFactor)) × ProfileAggressiveness

• Sistema ocioso → espera menor; sistema lento → espera maior
• Ideal quando a espera é uma "cortesia" ao sistema, não um requisito

O motor mantém um arquivo ~/.nano_wait_learning.json que registra um bias por perfil via EMA (Exponential Moving Average), calibrando-se com cada execução.

from nano_wait import AdaptiveLearning

al = AdaptiveLearning("default")
print(al.stats())
# {'profile': 'default', 'bias': 0.97, 'samples': 42, 'success_rate': 0.976}

print(AdaptiveLearning.all_profiles_stats())

al.reset()

🌐 Utilitários de Rede

from nano_wait import has_internet

if has_internet():
    wait(2, smart=True)
else:
    wait(5, profile="safe")  # rede instável → mais conservador

Wi-Fi awareness (requer pip install nano-wait[wifi]):

wait(2, wifi="MeuSSID", smart=True)

🐛 Exceções

from nano_wait import WaitTimeoutError, InvalidProfileError

try:
    wait(lambda: False, timeout=1, raise_on_timeout=True)
except WaitTimeoutError as e:
    print(f"Timeout: {e}")

🆚 NanoWait vs time.sleep()

wait(2) garante pelo menos 2s — nunca surpreende seus testes com esperas menores. wait(2, smart=True) pode acelerar em sistemas ociosos — use quando a espera é uma cortesia, não um requisito.

📄 Licença

MIT © NanoWait Team