nano-wait 4.0.0

Adaptive waiting and execution engine — replaces time.sleep() with system-aware, deterministic waiting.

NanoWait: The Adaptive Wait Engine for Python

🚀 What is NanoWait?

NanoWait is a deterministic and adaptive execution wait engine designed to replace Python’s standard time.sleep().

Instead of waiting a fixed amount of time, NanoWait dynamically adjusts the effective wait duration based on system load (CPU/RAM) and optionally Wi‑Fi signal strength, ensuring automation scripts remain reliable across slow or overloaded environments.

In short: you request a base time (e.g. wait(5)), and NanoWait guarantees a safe, context‑aware wait that never exceeds the requested time and never drops below a minimal execution floor.

---

🛠️ Installation

pip install nano_wait

Optional Module — Vision Mode

Visual waiting (icon/state detection) was intentionally moved to a dedicated package to keep NanoWait lightweight and deterministic.

pip install nano-wait-vision

If Vision Mode is not installed, NanoWait will raise a clear runtime error when visual features are requested.

---

💡 Quick Start

from nano_wait import wait
import time

# Standard sleep
start = time.time()
time.sleep(5)
print(f"time.sleep(): {time.time() - start:.2f}s")

# Adaptive wait
start = time.time()
wait(5)
print(f"nano_wait.wait(): {time.time() - start:.2f}s")

NanoWait never waits longer than the requested base time and applies a minimum internal delay of 50 ms to prevent CPU overuse.

---

⚙️ Core API

wait(
    t: float | None = None,
    *,
    wifi: str | None = None,
    speed: str | float = "normal",
    smart: bool = False,
    verbose: bool = False,
    log: bool = False
) -> float

Parameters

Parameter	Description
t	Base time in seconds (required for time‑based waiting).
wifi	Optional Wi‑Fi SSID used to evaluate signal quality.
speed	Execution speed preset or numeric value.
smart	Enables Smart Context Mode (dynamic speed calculation).
verbose	Prints debug information to stdout.
log	Writes execution data to nano_wait.log.

---

🧠 Smart Context Mode (smart=True)

When enabled, NanoWait calculates the execution speed automatically based on the average system context score.

wait(10, smart=True, verbose=True)

Example output:

[NanoWait] speed=3.42 factor=2.05 wait=4.878s

How Smart Speed Works

• PC Score → derived from CPU and memory usage
• Wi‑Fi Score → derived from RSSI (if enabled)

The final Smart Speed is:

speed = clamp( (pc_score + wifi_score) / 2 , 0.5 , 5.0 )

This value is used directly as the execution speed factor.

---

🌐 Wi‑Fi Awareness

If your automation depends on network stability, NanoWait can adapt waiting behavior based on Wi‑Fi signal strength.

wait(5, wifi="Office_Network")

Supported platforms:

• Windows (pywifi)
• macOS (airport)
• Linux (nmcli)

If Wi‑Fi data cannot be read, NanoWait safely falls back to neutral values.

---

⚡ Execution Speed Presets

NanoWait supports symbolic speed presets as well as numeric values.

Preset	Internal Value
slow	0.8
normal	1.5
fast	3.0
ultra	6.0

wait(2, speed="fast")
wait(2, speed=2.2)

Higher speeds reduce the nominal wait more aggressively.

---

🔬 How NanoWait Computes Time

System Context Scores

Score	Range	Meaning
PC Score	0–10	CPU & RAM availability
Wi‑Fi Score	0–10	Signal quality

Adjustment Factor

The adjustment factor is calculated as:

factor = max(0.2, (10 - risk) / speed)

Where:

risk = (pc_score + wifi_score) / 2

Final Wait Time

wait_time = clamp( t / factor , 0.05 , t )

Guarantees:

• Never waits longer than t
• Never waits less than 50 ms
• Deterministic across executions

---

🖥️ Command Line Interface (CLI)

NanoWait can be executed directly from the terminal:

nano-wait <time> [options]

Example:

nano-wait 5 --smart --verbose

Available flags:

• --wifi SSID
• --speed slow|normal|fast|ultra
• --smart
• --verbose
• --log

---

👁️ Visual Wait (Optional)

Visual waiting features (icons, UI states) are lazily loaded and require:

pip install nano-wait-vision

If not installed, NanoWait raises a clear ImportError explaining how to enable the feature.

---

🧪 Design Guarantees

• Deterministic behavior
• No busy‑waiting
• Safe fallback paths
• Cross‑platform support
• Production‑ready API

---

🤝 Contribution & License

NanoWait is open‑source and MIT‑licensed.

Issues, discussions, and pull requests are welcome.

Author: Luiz Filipe Seabra de Marco License: MIT