nano-wait 4.0.4__py3-none-any.whl

nano_wait/__init__.py

@@ -0,0 +1,4 @@
+from .nano_wait import wait
+from .core import NanoWait
+
+__all__ = ["wait", "NanoWait"]

nano_wait/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    main()

nano_wait/cli.py

@@ -0,0 +1,137 @@
+# cli.py
+import argparse
+import os
+
+from .nano_wait import wait
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Nano-Wait — Adaptive smart wait for Python."
+    )
+
+    # ------------------------
+    # Core arguments
+    # ------------------------
+    parser.add_argument(
+        "time",
+        type=float,
+        help="Base time in seconds"
+    )
+
+    parser.add_argument(
+        "--wifi",
+        type=str,
+        help="Wi-Fi SSID (optional)"
+    )
+
+    parser.add_argument(
+        "--speed",
+        type=str,
+        default="normal",
+        help="slow | normal | fast | ultra | numeric value"
+    )
+
+    parser.add_argument(
+        "--smart",
+        action="store_true",
+        help="Enable Smart Context Mode (auto speed)"
+    )
+
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Show debug output"
+    )
+
+    parser.add_argument(
+        "--log",
+        action="store_true",
+        help="Write log file (nano_wait.log)"
+    )
+
+    # ------------------------
+    # Explain mode
+    # ------------------------
+    parser.add_argument(
+        "--explain",
+        action="store_true",
+        help="Explain how the wait time was calculated"
+    )
+
+    # ------------------------
+    # Local Telemetry (opt-in)
+    # ------------------------
+    parser.add_argument(
+        "--telemetry",
+        action="store_true",
+        help="Enable local experimental telemetry (no remote collection)"
+    )
+
+    # ------------------------
+    # Headless mode (macOS safe)
+    # ------------------------
+    parser.add_argument(
+        "--headless",
+        action="store_true",
+        help="Disable any UI / Tk / dashboard (recommended on macOS & CI)"
+    )
+
+    # ------------------------
+    # Execution Profile
+    # ------------------------
+    parser.add_argument(
+        "--profile",
+        type=str,
+        choices=["ci", "testing", "rpa"],
+        help="Execution profile to adjust wait behavior"
+    )
+
+    args = parser.parse_args()
+
+    # ------------------------
+    # Force headless behavior
+    # ------------------------
+    if args.headless:
+        # Environment flag that NanoWait (and submodules) can read
+        os.environ["NANOWAIT_HEADLESS"] = "1"
+
+        # Safety: disable telemetry UI automatically
+        if args.telemetry:
+            print("[NanoWait] Headless mode enabled → telemetry UI disabled")
+            args.telemetry = False
+
+    # ------------------------
+    # Execute NanoWait
+    # ------------------------
+    result = wait(
+        t=args.time,
+        wifi=args.wifi,
+        speed=args.speed,
+        smart=args.smart,
+        verbose=args.verbose,
+        log=args.log,
+        explain=args.explain,
+        telemetry=args.telemetry,
+        profile=args.profile
+    )
+
+    # ------------------------
+    # Output explain
+    # ------------------------
+    if args.explain:
+        print("\n--- NanoWait Explain Report ---")
+
+        if isinstance(result, tuple):
+            report, telemetry = result
+            print(report.explain())
+
+            if telemetry is not None:
+                print("\n--- Telemetry Summary ---")
+                print(telemetry)
+        else:
+            print(result.explain())
+
+
+if __name__ == "__main__":
+    main()

nano_wait/core.py

@@ -0,0 +1,159 @@
+# core.py
+from dataclasses import dataclass
+from typing import Optional
+
+@dataclass(frozen=True)
+class ExecutionProfile:
+    name: str
+    aggressiveness: float      # multiplicador para intervalos adaptativos
+    tolerance: float           # permissividade a falhas temporárias
+    poll_interval: float       # base para time.sleep
+    verbose: bool              # mostra debug automaticamente
+
+# Perfis padrão
+PROFILES = {
+    "ci": ExecutionProfile("ci", aggressiveness=0.5, tolerance=0.9, poll_interval=0.05, verbose=True),
+    "testing": ExecutionProfile("testing", aggressiveness=1.0, tolerance=0.7, poll_interval=0.1, verbose=True),
+    "rpa": ExecutionProfile("rpa", aggressiveness=2.0, tolerance=0.5, poll_interval=0.2, verbose=False),
+    "default": ExecutionProfile("default", aggressiveness=1.0, tolerance=0.8, poll_interval=0.1, verbose=False)
+}
+
+class NanoWait:
+    def __init__(self, profile: Optional[str] = None):
+        import platform
+        self.system = platform.system().lower()
+        self.profile = PROFILES.get(profile, PROFILES["default"])
+
+        # Wi-Fi setup
+        if self.system == "windows":
+            try:
+                import pywifi
+                self.wifi = pywifi.PyWiFi()
+                self.interface = self.wifi.interfaces()[0]
+            except Exception:
+                self.wifi = None
+                self.interface = None
+        else:
+            self.wifi = None
+            self.interface = None
+
+    # ------------------------
+    # Context collection
+    # ------------------------
+
+    def get_pc_score(self) -> float:
+        import psutil
+        try:
+            cpu = psutil.cpu_percent(interval=1)
+            mem = psutil.virtual_memory().percent
+            cpu_score = max(0, min(10, 10 - cpu / 10))
+            mem_score = max(0, min(10, 10 - mem / 10))
+            return round((cpu_score + mem_score) / 2, 2)
+        except Exception:
+            return 5.0
+
+    def get_wifi_signal(self, ssid: str | None = None) -> float:
+        try:
+            if self.system == "windows" and self.interface:
+                self.interface.scan()
+                import time
+                time.sleep(2)
+                for net in self.interface.scan_results():
+                    if ssid is None or net.ssid == ssid:
+                        return max(0, min(10, (net.signal + 100) / 10))
+
+            elif self.system == "darwin":
+                import subprocess
+                out = subprocess.check_output(
+                    [
+                        "/System/Library/PrivateFrameworks/Apple80211.framework/"
+                        "Versions/Current/Resources/airport",
+                        "-I"
+                    ],
+                    text=True
+                )
+                line = [l for l in out.splitlines() if "agrCtlRSSI" in l][0]
+                rssi = int(line.split(":")[1].strip())
+                return max(0, min(10, (rssi + 100) / 10))
+
+            elif self.system == "linux":
+                import subprocess
+                out = subprocess.check_output(
+                    ["nmcli", "-t", "-f", "ACTIVE,SSID,SIGNAL", "dev", "wifi"],
+                    text=True
+                )
+                for l in out.splitlines():
+                    active, name, sig = l.split(":")
+                    if active == "yes" or (ssid and name == ssid):
+                        return max(0, min(10, int(sig) / 10))
+        except Exception:
+            pass
+
+        return 5.0
+
+    def snapshot_context(self, ssid: str | None = None) -> dict:
+        """
+        Captures an immutable snapshot of system context.
+        This is the foundation for deterministic explain mode.
+        """
+        pc = self.get_pc_score()
+        wifi = self.get_wifi_signal(ssid) if ssid else None
+
+        return {
+            "pc_score": pc,
+            "wifi_score": wifi
+        }
+
+    # ------------------------
+    # Smart Context
+    # ------------------------
+
+    def smart_speed(self, ssid: str | None = None) -> float:
+        context = self.snapshot_context(ssid)
+        pc = context["pc_score"]
+        wifi = context["wifi_score"] if context["wifi_score"] is not None else 5.0
+
+        risk = (pc + wifi) / 2
+        return round(max(0.5, min(5.0, risk)), 2)
+
+    # ------------------------
+    # Wait computation (pure math)
+    # ------------------------
+
+    def compute_wait_wifi(
+        self,
+        speed: float,
+        ssid: str | None = None,
+        *,
+        context: dict | None = None
+    ) -> float:
+        if context is None:
+            context = self.snapshot_context(ssid)
+
+        pc = context["pc_score"]
+        wifi = context["wifi_score"] if context["wifi_score"] is not None else 5.0
+
+        risk = (pc + wifi) / 2
+        return max(0.2, (10 - risk) / speed)
+
+    def compute_wait_no_wifi(
+        self,
+        speed: float,
+        *,
+        context: dict | None = None
+    ) -> float:
+        if context is None:
+            context = self.snapshot_context()
+
+        pc = context["pc_score"]
+        return max(0.2, (10 - pc) / speed)
+
+    # ------------------------
+    # Apply Execution Profile
+    # ------------------------
+
+    def apply_profile(self, base_wait: float) -> float:
+        """
+        Adjusts wait time according to current execution profile.
+        """
+        return base_wait * self.profile.aggressiveness

nano_wait/dashboard.py

@@ -0,0 +1,132 @@
+# dashboard.py
+import threading
+import queue
+import tkinter as tk
+from tkinter import ttk
+from time import sleep
+
+
+class TelemetryDashboard(threading.Thread):
+    def __init__(self, telemetry_queue: queue.Queue):
+        super().__init__(daemon=True)
+        self.q = telemetry_queue
+        self.running = True
+
+    def run(self):
+        self.root = tk.Tk()
+        self.root.title("NanoWait — Telemetry Dashboard")
+        self.root.geometry("420x260")
+        self.root.resizable(False, False)
+
+        self.factor_var = tk.StringVar(value="—")
+        self.interval_var = tk.StringVar(value="—")
+        self.count_var = tk.StringVar(value="0")
+
+        ttk.Label(self.root, text="NanoWait Telemetry", font=("Arial", 14, "bold")).pack(pady=10)
+
+        frame = ttk.Frame(self.root)
+        frame.pack(pady=10)
+
+        ttk.Label(frame, text="Adaptive Factor:").grid(row=0, column=0, sticky="w")
+        ttk.Label(frame, textvariable=self.factor_var).grid(row=0, column=1, sticky="e")
+
+        ttk.Label(frame, text="Interval (s):").grid(row=1, column=0, sticky="w")
+        ttk.Label(frame, textvariable=self.interval_var).grid(row=1, column=1, sticky="e")
+
+        ttk.Label(frame, text="Adjustments:").grid(row=2, column=0, sticky="w")
+        ttk.Label(frame, textvariable=self.count_var).grid(row=2, column=1, sticky="e")
+
+        ttk.Separator(self.root).pack(fill="x", pady=10)
+
+        self.status = ttk.Label(self.root, text="Running…", foreground="green")
+        self.status.pack()
+
+        self.root.after(100, self.poll_queue)
+        self.root.mainloop()
+
+    def poll_queue(self):
+        try:
+            while not self.q.empty():
+                data = self.q.get_nowait()
+
+                if data == "__STOP__":
+                    self.status.config(text="Finished", foreground="gray")
+                    self.running = False
+                    self.root.after(800, self.root.destroy)
+                    return
+
+                self.factor_var.set(str(data["factor"]))
+                self.interval_var.set(str(data["interval"]))
+                self.count_var.set(str(data["count"]))
+
+        except Exception:
+            pass
+
+        if self.running:
+            self.root.after(100, self.poll_queue)
+# dashboard.py
+import threading
+import queue
+import tkinter as tk
+from tkinter import ttk
+from time import sleep
+
+
+class TelemetryDashboard(threading.Thread):
+    def __init__(self, telemetry_queue: queue.Queue):
+        super().__init__(daemon=True)
+        self.q = telemetry_queue
+        self.running = True
+
+    def run(self):
+        self.root = tk.Tk()
+        self.root.title("NanoWait — Telemetry Dashboard")
+        self.root.geometry("420x260")
+        self.root.resizable(False, False)
+
+        self.factor_var = tk.StringVar(value="—")
+        self.interval_var = tk.StringVar(value="—")
+        self.count_var = tk.StringVar(value="0")
+
+        ttk.Label(self.root, text="NanoWait Telemetry", font=("Arial", 14, "bold")).pack(pady=10)
+
+        frame = ttk.Frame(self.root)
+        frame.pack(pady=10)
+
+        ttk.Label(frame, text="Adaptive Factor:").grid(row=0, column=0, sticky="w")
+        ttk.Label(frame, textvariable=self.factor_var).grid(row=0, column=1, sticky="e")
+
+        ttk.Label(frame, text="Interval (s):").grid(row=1, column=0, sticky="w")
+        ttk.Label(frame, textvariable=self.interval_var).grid(row=1, column=1, sticky="e")
+
+        ttk.Label(frame, text="Adjustments:").grid(row=2, column=0, sticky="w")
+        ttk.Label(frame, textvariable=self.count_var).grid(row=2, column=1, sticky="e")
+
+        ttk.Separator(self.root).pack(fill="x", pady=10)
+
+        self.status = ttk.Label(self.root, text="Running…", foreground="green")
+        self.status.pack()
+
+        self.root.after(100, self.poll_queue)
+        self.root.mainloop()
+
+    def poll_queue(self):
+        try:
+            while not self.q.empty():
+                data = self.q.get_nowait()
+
+                if data == "__STOP__":
+                    self.status.config(text="Finished", foreground="gray")
+                    self.running = False
+                    self.root.after(800, self.root.destroy)
+                    return
+
+                self.factor_var.set(str(data["factor"]))
+                self.interval_var.set(str(data["interval"]))
+                self.count_var.set(str(data["count"]))
+
+        except Exception:
+            pass
+
+        if self.running:
+            self.root.after(100, self.poll_queue)

nano_wait/exceptions.py

@@ -0,0 +1,2 @@
+class VisionTimeout(Exception):
+    """Raised when a visual condition is not detected within the timeout."""

nano_wait/explain.py

@@ -0,0 +1,47 @@
+from dataclasses import dataclass, asdict
+from typing import Optional
+from datetime import datetime
+
+
+@dataclass(frozen=True)
+class ExplainReport:
+    requested_time: Optional[float]
+    final_time: float
+
+    speed_input: str | float
+    speed_value: float
+    smart: bool
+
+    cpu_score: float
+    wifi_score: Optional[float]
+    factor: float
+
+    min_floor_applied: bool
+    max_cap_applied: bool
+
+    timestamp: str
+    nano_wait_version: str = "4.1.4"
+
+    def to_dict(self):
+        return asdict(self)
+
+    def explain(self) -> str:
+        lines = [
+            f"Requested time: {self.requested_time}s",
+            f"Final wait time: {self.final_time}s",
+            f"Speed input: {self.speed_input} → {self.speed_value}",
+            f"Smart mode: {self.smart}",
+            f"CPU score: {self.cpu_score}",
+        ]
+
+        if self.wifi_score is not None:
+            lines.append(f"Wi-Fi score: {self.wifi_score}")
+
+        lines.extend([
+            f"Adaptive factor: {self.factor}",
+            f"Minimum floor applied: {self.min_floor_applied}",
+            f"Maximum cap applied: {self.max_cap_applied}",
+            f"Timestamp: {self.timestamp}",
+        ])
+
+        return "\n".join(lines)

nano_wait/nano_wait.py

@@ -0,0 +1,218 @@
+# nano_wait.py
+import time
+import queue
+from typing import overload
+from datetime import datetime
+
+from .core import NanoWait, PROFILES
+from .utils import log_message, get_speed_value
+from .exceptions import VisionTimeout
+from .explain import ExplainReport
+from .telemetry import TelemetrySession
+from .dashboard import TelemetryDashboard
+
+_ENGINE = None
+
+
+def _engine():
+    global _ENGINE
+    if _ENGINE is None:
+        _ENGINE = NanoWait()
+    return _ENGINE
+
+
+# --------------------------------------
+# Public API
+# --------------------------------------
+
+@overload
+def wait(t: float, **kwargs) -> float: ...
+
+
+@overload
+def wait(*, until: str, **kwargs): ...
+
+
+@overload
+def wait(*, icon: str, **kwargs): ...
+
+
+def wait(
+    t: float | None = None,
+    *,
+    until: str | None = None,
+    icon: str | None = None,
+    region=None,
+    timeout: float = 15.0,
+    wifi: str | None = None,
+    speed: str | float = "normal",
+    smart: bool = False,
+    verbose: bool = False,
+    log: bool = False,
+    explain: bool = False,
+    telemetry: bool = False,
+    profile: str | None = None
+):
+    """
+    Adaptive deterministic wait with optional explainable execution,
+    execution profiles and local experimental telemetry with live dashboard.
+    """
+
+    nw = _engine()
+
+    # ------------------------
+    # Apply execution profile
+    # ------------------------
+    if profile:
+        nw.profile = PROFILES.get(profile, PROFILES["default"])
+
+    verbose = verbose or nw.profile.verbose
+
+    # ------------------------
+    # Context snapshot
+    # ------------------------
+    context = nw.snapshot_context(wifi)
+    cpu_score = context["pc_score"]
+    wifi_score = context["wifi_score"]
+
+    # ------------------------
+    # Telemetry queue + dashboard
+    # ------------------------
+    telemetry_queue = queue.Queue() if telemetry else None
+
+    if telemetry:
+        TelemetryDashboard(telemetry_queue).start()
+
+    telemetry_session = TelemetrySession(
+        enabled=telemetry,
+        cpu_score=cpu_score,
+        wifi_score=wifi_score,
+        profile=nw.profile.name,
+        queue=telemetry_queue
+    )
+
+    telemetry_session.start()
+
+    # ------------------------
+    # Speed resolution
+    # ------------------------
+    speed_value = nw.smart_speed(wifi) if smart else get_speed_value(speed)
+
+    # --------------------------------------
+    # VISUAL WAIT
+    # --------------------------------------
+    if until or icon:
+        from .vision import VisionMode
+
+        vision = VisionMode()
+        start = time.time()
+
+        while time.time() - start < timeout:
+
+            if until:
+                state = vision.observe([region] if region else None)
+                if state == until:
+                    telemetry_session.stop()
+                    return vision.detect_icon("", region)
+
+            if icon:
+                result = vision.detect_icon(icon, region)
+                if result.detected:
+                    telemetry_session.stop()
+                    return result
+
+            factor = (
+                nw.compute_wait_wifi(speed_value, wifi, context=context)
+                if wifi
+                else nw.compute_wait_no_wifi(speed_value, context=context)
+            )
+
+            interval = max(0.05, min(0.5, 1 / factor))
+            interval = nw.apply_profile(interval)
+
+            telemetry_session.record(
+                factor=factor,
+                interval=interval
+            )
+
+            time.sleep(interval)
+
+        telemetry_session.stop()
+        raise VisionTimeout("Visual condition not detected")
+
+    # --------------------------------------
+    # TIME WAIT
+    # --------------------------------------
+    factor = (
+        nw.compute_wait_wifi(speed_value, wifi, context=context)
+        if wifi
+        else nw.compute_wait_no_wifi(speed_value, context=context)
+    )
+
+    raw_wait = t / factor if t else factor
+    wait_time = round(max(0.05, min(raw_wait, t or raw_wait)), 3)
+    wait_time = nw.apply_profile(wait_time)
+
+    min_floor_applied = raw_wait < 0.05
+    max_cap_applied = t is not None and raw_wait > t
+
+    telemetry_session.record(
+        factor=factor,
+        interval=wait_time
+    )
+
+    # ------------------------
+    # Verbose / log
+    # ------------------------
+    if verbose:
+        print(
+            f"[NanoWait | {nw.profile.name}] "
+            f"speed={speed_value:.2f} "
+            f"factor={factor:.2f} "
+            f"wait={wait_time:.3f}s"
+        )
+
+    if log:
+        log_message(
+            f"[NanoWait | {nw.profile.name}] "
+            f"speed={speed_value:.2f} "
+            f"factor={factor:.2f} "
+            f"wait={wait_time:.3f}s"
+        )
+
+    # ------------------------
+    # Explain report
+    # ------------------------
+    report = None
+    if explain:
+        report = ExplainReport(
+            requested_time=t,
+            final_time=wait_time,
+            speed_input=speed,
+            speed_value=speed_value,
+            smart=smart,
+            cpu_score=cpu_score,
+            wifi_score=wifi_score,
+            factor=factor,
+            min_floor_applied=min_floor_applied,
+            max_cap_applied=max_cap_applied,
+            timestamp=datetime.utcnow().isoformat()
+        )
+
+    telemetry_session.stop()
+
+    # ------------------------
+    # Execute wait
+    # ------------------------
+    time.sleep(wait_time)
+
+    if explain and telemetry:
+        return report, telemetry_session.summary()
+
+    if explain:
+        return report
+
+    if telemetry:
+        return wait_time, telemetry_session.summary()
+
+    return wait_time

nano_wait/telemetry.py

@@ -0,0 +1,77 @@
+# telemetry.py
+from dataclasses import dataclass, field
+from typing import List, Optional
+from datetime import datetime
+import queue
+
+
+@dataclass(frozen=True)
+class TelemetryEvent:
+    timestamp: str
+    factor: float
+    interval: float
+
+
+@dataclass
+class TelemetrySession:
+    enabled: bool = False
+    start_time: Optional[float] = None
+    end_time: Optional[float] = None
+
+    cpu_score: Optional[float] = None
+    wifi_score: Optional[float] = None
+    profile: Optional[str] = None
+
+    events: List[TelemetryEvent] = field(default_factory=list)
+
+    # 👇 NOVO
+    queue: Optional[queue.Queue] = None
+
+    def start(self):
+        if self.enabled:
+            from time import time
+            self.start_time = time()
+
+    def stop(self):
+        if self.enabled:
+            from time import time
+            self.end_time = time()
+            if self.queue:
+                self.queue.put("__STOP__")
+
+    def record(self, *, factor: float, interval: float):
+        if not self.enabled:
+            return
+
+        event = TelemetryEvent(
+            timestamp=datetime.utcnow().isoformat(),
+            factor=round(factor, 4),
+            interval=round(interval, 4),
+        )
+
+        self.events.append(event)
+
+        if self.queue:
+            self.queue.put({
+                "factor": event.factor,
+                "interval": event.interval,
+                "count": len(self.events)
+            })
+
+    def summary(self) -> dict:
+        if not self.enabled:
+            return {}
+
+        total_time = (
+            round(self.end_time - self.start_time, 4)
+            if self.start_time and self.end_time
+            else None
+        )
+
+        return {
+            "profile": self.profile,
+            "cpu_score": self.cpu_score,
+            "wifi_score": self.wifi_score,
+            "adjustments": len(self.events),
+            "total_time": total_time,
+        }

nano_wait/utils.py

@@ -0,0 +1,13 @@
+from datetime import datetime
+
+def get_speed_value(speed):
+    """Converts speed preset or numeric input to float."""
+    speed_map = {"slow": 0.8, "normal": 1.5, "fast": 3.0, "ultra": 6.0}
+    if isinstance(speed, str):
+        return speed_map.get(speed.lower(), 1.5)
+    return float(speed)
+
+def log_message(text: str):
+    """Saves messages to nano_wait.log."""
+    with open("nano_wait.log", "a") as f:
+        f.write(f"[{datetime.now().strftime('%Y-%m-%d %H:%M:%S')}] {text}\n")

nano_wait/vision.py

@@ -0,0 +1,4 @@
+raise ImportError(
+    "Vision features were moved to 'nano-wait-vision'. "
+    "Install with: pip install nano-wait-vision"
+)

nano_wait-4.0.4.dist-info/METADATA

@@ -0,0 +1,380 @@
+Metadata-Version: 2.4
+Name: nano_wait
+Version: 4.0.4
+Summary: Adaptive waiting and execution engine — replaces time.sleep() with system-aware, deterministic waiting.
+Author: Luiz Filipe Seabra de Marco
+Author-email: luizfilipeseabra@icloud.com
+License: MIT
+Keywords: automation,adaptive wait,smart wait,execution engine,system-aware,deterministic automation,rpa core,testing,performance,psutil,wifi awareness,system context,sleep replacement
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Utilities
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: psutil
+Requires-Dist: pywifi
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: keywords
+Dynamic: license
+Dynamic: license-file
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# NanoWait: The Adaptive Wait Engine for Python
+
+[![PyPI version](https://img.shields.io/pypi/v/nano_wait.svg)](https://pypi.org/project/nano_wait/)
+[![License](https://img.shields.io/pypi/l/nano_wait.svg)](https://github.com/luizfilipe/NanoWait/blob/main/LICENSE)
+[![Python Version](https://img.shields.io/pypi/pyversions/nano_wait.svg)](https://pypi.org/project/nano_wait/)
+
+## 🚀 What is NanoWait?
+
+**NanoWait** is a deterministic and adaptive execution wait engine designed to replace Python's standard `time.sleep()`. Instead of waiting for a fixed duration, NanoWait dynamically adjusts the wait time based on **system load (CPU/RAM)** and, optionally, **Wi-Fi signal strength**, ensuring automation scripts remain reliable even in slow or overloaded environments.
+
+With the introduction of **Execution Profiles**, NanoWait now offers a semantic layer to manage wait behavior, allowing you to define the operational context clearly and consistently.
+
+> **In summary:** you request a base time (e.g., `wait(5)`), and NanoWait ensures a *safe and context-aware wait* that never exceeds the requested time and never falls below a minimum execution floor.
+
+### Cross-Platform Stability & Headless Environments
+
+NanoWait has undergone significant structural modifications focused on **cross-platform stability**, especially for macOS, and **safe usage in headless environments** (CI, RPA, servers). It explicitly differentiates between graphical and headless modes. In headless environments, no graphical UI is instantiated, preventing crashes like `NSWindow should only be instantiated on the main thread` on macOS with Tkinter issues. This ensures total stability in macOS, CI/CD pipelines, and remote execution.
+
+---
+
+## 🛠️ Installation
+
+```bash
+pip install nano_wait
+```
+
+### Optional Module — Vision Mode
+
+Visual waiting (icon/state detection) has been intentionally moved to a dedicated package to keep NanoWait lightweight and deterministic.
+
+```bash
+pip install nano-wait-vision
+```
+
+If Vision Mode is not installed, NanoWait will raise a clear runtime error when visual functionalities are requested.
+
+---
+
+## 💡 Quick Guide
+
+```python
+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 excessive CPU usage.
+
+---
+
+## ⚙️ Core API
+
+```python
+wait(
+    t: float | None = None,
+    *,
+    wifi: str | None = None,
+    speed: str | float = "normal",
+    smart: bool = False,
+    explain: bool = False,
+    verbose: bool = False,
+    log: bool = False,
+    profile: str | None = None,
+    headless: bool = False # New parameter for explicit headless mode
+) -> float | ExplainReport
+```
+
+### Parameters
+
+| Parameter | Description                                                                 |
+|-----------|---------------------------------------------------------------------------|
+| `t`       | Base time in seconds (required for time-based waiting).                   |
+| `wifi`    | Wi-Fi network SSID to assess signal quality (optional).                   |
+| `speed`   | Execution speed preset or numeric value.                                  |
+| `smart`   | Activates Smart Context Mode (dynamic speed calculation).                 |
+| `explain` | Activates Explain Mode, which returns a detailed decision report.         |
+| `verbose` | Prints debug information to `stdout`.                                     |
+| `log`     | Writes execution data to `nano_wait.log`.                                 |
+| `profile` | Selects a predefined execution profile (e.g., "ci", "rpa").             |
+| `headless`| Explicitly forces headless mode, disabling graphical UI elements.           |
+
+---
+
+## 🧩 Execution Profiles
+
+Execution Profiles introduce a semantic layer over NanoWait's adaptive wait engine. Instead of manually adjusting isolated parameters (speed, aggressiveness, verbosity), you can select an execution profile that represents the operational context in which your code is running — such as continuous integration (CI), automated tests, or robotic process automation (RPA).
+
+Each profile encapsulates a coherent set of decisions, ensuring consistency, readability, and reduced cognitive complexity for the user.
+
+### 🎯 Why use Execution Profiles?
+
+Without profiles, scripts tend to accumulate fragile adjustments:
+
+```python
+wait(2, speed="fast", smart=True, verbose=True)
+```
+
+With Execution Profiles, the focus shifts to the environment, not mechanical details:
+
+```python
+wait(2, profile="ci")
+```
+
+### ⚙️ How to use
+
+Basic usage:
+
+```python
+from nano_wait import wait
+
+# Executes the wait using the Continuous Integration profile
+wait(2, profile="ci")
+```
+
+If no profile is specified, NanoWait uses the default profile.
+
+### 🧪 Available Profiles
+
+| Profile   | Recommended Use                      | General Behavior                        |
+|-----------|--------------------------------------|-----------------------------------------|
+| `ci`      | CI/CD Pipelines                      | Aggressive waits, verbose enabled       |
+| `testing` | Local Automated Tests                | Balance between speed and stability     |
+| `rpa`     | Interface and Human Workflow Automation | More conservative waits                 |
+| `default` | Generic Execution                    | Balanced behavior                       |
+
+### 🧠 What does an Execution Profile control?
+
+Internally, each profile defines:
+
+*   Aggressiveness of time adaptation
+*   Tolerance to transient instabilities
+*   Polling interval
+*   Default verbosity (automatic debug)
+
+These parameters are applied deterministically to each execution.
+
+### 🔄 Integration with Smart Context Mode
+
+Execution Profiles do not replace Smart Context Mode — they complement each other.
+
+```python
+wait(
+    t=3,
+    smart=True,
+    profile="testing"
+)
+```
+
+In this example:
+
+*   Smart Mode calculates the optimal speed based on the system
+*   The Execution Profile adjusts the overall wait behavior
+
+### 🧪 Comparative Example
+
+Without Execution Profiles:
+
+```python
+wait(
+    t=2,
+    speed="fast",
+    smart=True,
+    verbose=True
+)
+```
+
+With Execution Profiles:
+
+```python
+wait(
+    t=2,
+    profile="ci"
+)
+```
+
+The second example is more readable, more consistent, and less fragile to future changes.
+
+---
+
+## 🔬 Explain Mode (`explain=True`)
+
+Explain Mode makes NanoWait's waiting mechanism deterministic, auditable, and explainable. It does not alter the wait behavior but **reveals how the decision was made**.
+
+When activated, `wait()` returns an `ExplainReport` object (instead of a dictionary as previously). This report contains all factors used in the calculation, ideal for debugging, auditing, and benchmarking. The `ExplainReport` includes:
+
+*   Requested time
+*   Final applied time
+*   Configured and resolved speed
+*   Smart Mode usage
+*   CPU score
+*   Wi-Fi score
+*   Adaptive factor
+*   Application of minimum floor or maximum cap
+*   Execution timestamp
+
+This makes the wait behavior fully auditable and reproducible, providing total transparency for critical environments.
+
+### Code Example
+
+```python
+from nano_wait import wait
+
+report = wait(
+    t=1.5,
+    speed="fast",
+    smart=True,
+    explain=True
+)
+
+print(report.explain()) # Use .explain() method for a formatted string output
+```
+
+**Example `ExplainReport` output (simplified):**
+
+```
+Requested time: 1.5s
+Final wait time: 0.7s
+Speed input: fast -> 0.5
+Smart mode: True
+CPU score: 0.62
+Adaptive factor: 1.39
+Execution profile: default
+```
+
+---
+
+## 🧠 Smart Context Mode (`smart=True`)
+
+When activated, NanoWait automatically calculates the execution speed based on the **average system context score**.
+
+```python
+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 activated).
+
+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 its waiting behavior based on Wi-Fi signal strength.
+
+```python
+wait(5, wifi="MyNetwork_5G")
+```
+
+Supported platforms:
+
+*   Windows (`pywifi`)
+*   macOS (`airport`)
+*   Linux (`nmcli`)
+
+---
+
+## 🖥️ Command Line Interface (CLI)
+
+The CLI has been updated to reflect 100% of the API's capabilities, making the tool easy to test, debug, and use in real scripts.
+
+**CLI can be executed locally via:**
+
+```bash
+python -m nano_wait.cli 3
+```
+
+**Or as an installed command:**
+
+```bash
+nano-wait 3 --smart --explain
+```
+
+**Supported flags:**
+
+*   `--smart`
+*   `--speed`
+*   `--wifi`
+*   `--verbose`
+*   `--log`
+*   `--explain`
+*   `--telemetry` (for local telemetry activation)
+*   `--profile`
+*   `--headless`
+
+---
+
+## 📊 Local Telemetry (Opt-in, No Remote Collection)
+
+NanoWait now includes an experimental, **fully opt-in local telemetry system**. There is **no remote data collection or transmission**.
+
+Telemetry records:
+
+*   `cpu_score`
+*   `wifi_score`
+*   `adaptive factor`
+*   `intervals`
+*   Active `profile`
+
+In graphical mode (when applicable), a local dashboard might be available. In headless mode, the UI is automatically deactivated. The objective is to allow analysis of wait behavior without compromising security or portability.
+
+---
+
+## 🛡️ Best Practices & Recommendations
+
+1.  **Use Profiles:** Prefer `wait(2, profile="testing")` over `wait(2, speed="fast")` for semantic clarity and robustness.
+2.  **Smart Mode in Production:** Activate `smart=True` in environments where CPU load is unpredictable to ensure adaptive waiting.
+3.  **Audit with Explain:** Use `explain=True` during debugging or intermittent test failures to understand how environmental factors influenced the wait duration.
+4.  **Explicit Headless:** When running in Docker, CI, or on servers without a display, explicitly use the `--headless` flag in the CLI or the `headless=True` parameter in the API to prevent unexpected UI attempts.
+
+---
+
+## 📄 License
+
+Distributed under the MIT License. See `LICENSE` for more information.

nano_wait-4.0.4.dist-info/RECORD

@@ -0,0 +1,17 @@
+nano_wait/__init__.py,sha256=SFhmXcZZGJqce153hEDQDaDekRLFs7yxsrDCMq7N6bM,87
+nano_wait/__main__.py,sha256=MSmt_5Xg84uHqzTN38JwgseJK8rsJn_11A8WD99VtEo,61
+nano_wait/cli.py,sha256=hY1oCu_T5Yjg0d2HuaxOPzQZRddf03oRlLb3RJWX-40,3283
+nano_wait/core.py,sha256=KIVNW-REpmKNPniHW8o85tw-_vTyvn_uvZxxcesmmc8,5362
+nano_wait/dashboard.py,sha256=VkDzsSSoc9h2q2W7GlVDCxzTVxQPZzaYYKNiO1b9qRI,4478
+nano_wait/exceptions.py,sha256=wgIXzSVkC_o8EvwuhA6ORP2pMzb8jRsSYr7z4J6_gHg,109
+nano_wait/explain.py,sha256=Bn9tokNMq2L6gk7wfgTS8cbSjK4nsgjz1gFYAv28I1k,1216
+nano_wait/nano_wait.py,sha256=jflBsNwtzmceWQTHeevfW1U3zOd4Ew7ijIlx6unNFeY,5588
+nano_wait/telemetry.py,sha256=cka6S3a4reNAL9WctWEuI0zmKxIu8GS-88uiF5yg0pQ,1896
+nano_wait/utils.py,sha256=28qjlES2Yw69mvaj52mmnRqWjtpxu3aG1GwG29dvBYw,486
+nano_wait/vision.py,sha256=NKzJAZFV3152EQBeeygpub8B0VTHo0L9Wt85CsgVa9k,127
+nano_wait-4.0.4.dist-info/licenses/LICENSE,sha256=iu3NnVehM00ZoIpIVkl44-9mCgXVh9iGYMZYXtMv0Mc,1084
+nano_wait-4.0.4.dist-info/METADATA,sha256=0BVeCFSy8jyXKNdMnrd-EbBJF2YxLWcN3x87gJEaFSw,12048
+nano_wait-4.0.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+nano_wait-4.0.4.dist-info/entry_points.txt,sha256=IISprKfo-qF43ML7ywqV22rUrTm0Gi2y_DpAN03kZhA,49
+nano_wait-4.0.4.dist-info/top_level.txt,sha256=dSiF3Wc3ZEB1pzcp_ubHZeb0OE7n1nPMntkL48uz6aI,10
+nano_wait-4.0.4.dist-info/RECORD,,

nano_wait-4.0.4.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

nano_wait-4.0.4.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+nano-wait = nano_wait.cli:main

nano_wait-4.0.4.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Luiz Filipe Seabra de marco
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

nano_wait-4.0.4.dist-info/top_level.txt

@@ -0,0 +1 @@
+nano_wait