wavexis 2.2.3__tar.gz → 2.2.5__tar.gz

{wavexis-2.2.3 → wavexis-2.2.5}/CHANGELOG.md

@@ -2,6 +2,25 @@
 
 All notable changes to wavexis are documented in this file.
 
+## v2.2.5 — 2026-07-07
+
+### Improved
+
+- Error messages now include actionable hints for common failures
+- `ElementNotFoundError` suggests `wavexis dom` and `wavexis screenshot` for debugging
+- `WaitTimeoutError` suggests increasing `--timeout` and alternative wait strategies
+- `NavigationError` suggests checking URL, `--timeout`, and `--proxy`
+- `SessionNotInitializedError` suggests `--headed` and checking Chromium installation
+- `BackendNotAvailableError` shows install commands for both backends
+- `MultiConfigError` suggests `--dry-run` to validate config
+
+## v2.2.4 — 2026-07-07
+
+### Added
+
+- Progress reporting for long-running operations (`batch`, `multi`, `scrape`)
+- `_progress(current, total, label)` helper shows `[n/total] — label` unless `--quiet`
+
 ## v2.2.3 — 2026-07-07
 
 ### Added

{wavexis-2.2.3 → wavexis-2.2.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wavexis
-Version: 2.2.3
+Version: 2.2.5
 Summary: Browser automation CLI — wraps cdpwave and bidiwave, no Node.js, no Chromium download
 Project-URL: Homepage, https://github.com/MathiasPaulenko/wavexis
 Project-URL: Repository, https://github.com/MathiasPaulenko/wavexis

{wavexis-2.2.3 → wavexis-2.2.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wavexis"
-version = "2.2.3"
+version = "2.2.5"
 description = "Browser automation CLI — wraps cdpwave and bidiwave, no Node.js, no Chromium download"
 readme = "README.md"
 license = { text = "MIT" }

{wavexis-2.2.3 → wavexis-2.2.5}/wavexis/__init__.py

@@ -1,3 +1,3 @@
 """wavexis — CLI de automatización de navegador."""
 
-__version__ = "2.2.3"
+__version__ = "2.2.5"

{wavexis-2.2.3 → wavexis-2.2.5}/wavexis/cli/_capture.py

@@ -18,7 +18,9 @@ from wavexis.actions.screenshot import ScreenshotAction
 from wavexis.cli._shared import (
     Output,
     _browser_options,
+    _echo,
     _get_backend,
+    _progress,
     _run_async,
     _write_json_output,
     app,
@@ -376,17 +378,24 @@ async def _scrape(
 ) -> list[dict[str, Any]]:
     """Async helper for scraping."""
     backend = _get_backend()
+    total = len(urls)
+    _echo(f"Scraping {total} URL(s)…")
     try:
         await backend.launch(_browser_options())
-        params = ScrapeParams(
-            urls=urls,
-            expression=expression,
-            file=file,
-            output_format="json",
-            selector=selector,
-            wait=WaitStrategy(strategy="load"),
-        )
-        return await ScrapeAction(params).execute(backend)
+        results: list[dict[str, Any]] = []
+        for i, url in enumerate(urls):
+            _progress(i + 1, total, url)
+            params = ScrapeParams(
+                urls=[url],
+                expression=expression,
+                file=file,
+                output_format="json",
+                selector=selector,
+                wait=WaitStrategy(strategy="load"),
+            )
+            result = await ScrapeAction(params).execute(backend)
+            results.extend(result)
+        return results
     finally:
         await backend.close()
 

{wavexis-2.2.3 → wavexis-2.2.5}/wavexis/cli/_shared.py

@@ -21,6 +21,7 @@ from wavexis.exceptions import (
     ElementNotFoundError,
     MultiConfigError,
     NavigationError,
+    SessionNotInitializedError,
     WaitTimeoutError,
     WavexisError,
 )
@@ -39,6 +40,7 @@ __all__ = [
     "MultiConfigError",
     "NavigationError",
     "Output",
+    "SessionNotInitializedError",
     "WaitTimeoutError",
     "WavexisError",
     "_browser_options",
@@ -48,6 +50,7 @@ __all__ = [
     "_get_ctx",
     "_handle_error",
     "_load_global_config",
+    "_progress",
     "_run_async",
     "_write_json_output",
     "app",
@@ -185,6 +188,21 @@ def _echo(msg: str) -> None:
         typer.echo(msg)
 
 
+def _progress(current: int, total: int, label: str = "") -> None:
+    """Print a progress indicator unless quiet mode is active.
+
+    Args:
+        current: Current item index (1-based).
+        total: Total number of items.
+        label: Optional label to prepend (e.g. URL or action name).
+    """
+    ctx = _get_ctx()
+    if ctx.quiet:
+        return
+    suffix = f" — {label}" if label else ""
+    typer.echo(f"[{current}/{total}]{suffix}")
+
+
 def _handle_error(e: Exception) -> None:
     """Handle a WavexisError with the correct exit code and message.
 
@@ -193,20 +211,28 @@ def _handle_error(e: Exception) -> None:
     """
     if isinstance(e, BackendNotAvailableError):
         Output.error(
-            "No backend available. Install cdpwave: pip install wavexis[cdp]"
+            "No backend available.\n"
+            "Hint: Install cdpwave with `pip install wavexis[cdp]`, "
+            "or bidiwave with `pip install wavexis[bidi]`."
         )
         raise typer.Exit(EXIT_BACKEND_ERROR) from e
+    if isinstance(e, SessionNotInitializedError):
+        Output.error(str(e))
+        raise typer.Exit(EXIT_BROWSER_ERROR) from e
     if isinstance(e, NavigationError):
-        Output.error(f"Navigation failed: {e}")
+        Output.error(str(e))
         raise typer.Exit(EXIT_BROWSER_ERROR) from e
     if isinstance(e, WaitTimeoutError):
-        Output.error(f"Timeout waiting: {e}")
+        Output.error(str(e))
         raise typer.Exit(EXIT_BROWSER_ERROR) from e
     if isinstance(e, ElementNotFoundError):
-        Output.error(f"Element not found: {e}")
+        Output.error(str(e))
         raise typer.Exit(EXIT_BROWSER_ERROR) from e
     if isinstance(e, MultiConfigError):
-        Output.error(f"Invalid multi config: {e}")
+        Output.error(
+            f"Invalid multi config: {e}\n"
+            "Hint: Run `wavexis multi <config> --dry-run` to validate the config."
+        )
         raise typer.Exit(EXIT_CONFIG_ERROR) from e
     if isinstance(e, WavexisError):
         Output.error(str(e))

{wavexis-2.2.3 → wavexis-2.2.5}/wavexis/cli/_workflow.py

@@ -19,6 +19,7 @@ from wavexis.cli._shared import (
     _echo,
     _get_backend,
     _handle_error,
+    _progress,
     _run_async,
     app,
 )
@@ -118,10 +119,20 @@ async def _multi(config_path: Any, parallel: bool = False) -> list[Any]:
     from wavexis.multi import execute_actions, parse_yaml
 
     actions = parse_yaml(config_path)
+    total = len(actions)
+    _echo(f"Executing {total} action(s)…")
     backend = _get_backend()
     await backend.launch(_browser_options())
     try:
-        return await execute_actions(actions, backend, parallel=parallel)
+        results: list[Any] = []
+        if parallel:
+            results = await execute_actions(actions, backend, parallel=True)
+        else:
+            for i, action in enumerate(actions):
+                _progress(i + 1, total, str(action))
+                result = await execute_actions([action], backend, parallel=False)
+                results.extend(result)
+        return results
     finally:
         await backend.close()
 
@@ -215,13 +226,22 @@ async def _batch(
         List of results (or exceptions) in the same order as urls.
     """
     semaphore = asyncio.Semaphore(parallel)
+    total = len(urls)
+    completed = 0
+    lock = asyncio.Lock()
 
     async def _run_one(url: str) -> Any:
+        nonlocal completed
         async with semaphore:
             try:
-                return await _batch_single(url, action, out_dir, expression)
+                result = await _batch_single(url, action, out_dir, expression)
+                return result
             except (WavexisError, OSError) as exc:
                 return exc
+            finally:
+                async with lock:
+                    completed += 1
+                    _progress(completed, total, url)
 
     tasks = [_run_one(u) for u in urls]
     return await asyncio.gather(*tasks)

{wavexis-2.2.3 → wavexis-2.2.5}/wavexis/exceptions.py

@@ -41,6 +41,21 @@ class BackendNotSupportedError(WavexisError):
 class SessionNotInitializedError(WavexisError):
     """Raised when a backend method is called before launch()."""
 
+    def __init__(self, msg: str | None = None) -> None:
+        """Initialize the error.
+
+        Args:
+            msg: Optional custom message.
+        """
+        if msg:
+            super().__init__(msg)
+        else:
+            super().__init__(
+                "Browser session not initialized. Call launch() first.\n"
+                "Hint: This usually means the browser failed to start. "
+                "Try --headed to see the browser window, or check if Chromium is installed."
+            )
+
 
 class NavigationError(WavexisError):
     """Raised when navigation fails or times out."""
@@ -52,7 +67,11 @@ class NavigationError(WavexisError):
             url: The URL that failed to navigate to.
             reason: The failure reason.
         """
-        super().__init__(f"Navigation to '{url}' failed: {reason}")
+        super().__init__(
+            f"Navigation to '{url}' failed: {reason}\n"
+            f"Hint: Check the URL is reachable, try --timeout 60000, "
+            f"or use --proxy if behind a firewall."
+        )
 
 
 class WaitTimeoutError(WavexisError):
@@ -66,7 +85,9 @@ class WaitTimeoutError(WavexisError):
             timeout_ms: The timeout duration in milliseconds.
         """
         super().__init__(
-            f"Wait strategy '{strategy}' timed out after {timeout_ms}ms"
+            f"Wait strategy '{strategy}' timed out after {timeout_ms}ms\n"
+            f"Hint: Increase timeout with --timeout {max(timeout_ms * 2, 60000)}, "
+            f"or use a different wait strategy (load, domcontentloaded, networkidle)."
         )
 
 
@@ -79,7 +100,11 @@ class ElementNotFoundError(WavexisError):
         Args:
             selector: The CSS selector that matched no elements.
         """
-        super().__init__(f"No element found matching selector: {selector}")
+        super().__init__(
+            f"No element found matching selector: {selector}\n"
+            f"Hint: Verify the selector with `wavexis dom --selector '{selector}'`, "
+            f"or use `wavexis screenshot` to inspect the page visually."
+        )
 
 
 class ActionError(WavexisError):