stackvox 0.10.0__tar.gz → 0.12.0__tar.gz

{stackvox-0.10.0/stackvox.egg-info → stackvox-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.10.0
+Version: 0.12.0
 Summary: Offline TTS library using Kokoro-82M
 Author-email: "StackOne Technologies Ltd." <support@stackone.com>
 License-Expression: Apache-2.0
@@ -103,7 +103,11 @@ stackvox speak --normalize --file post.md       # normalize, then synthesize
 stackvox say   --normalize "**Shipped** 1,198.9 MPG"   # normalize, then send to daemon
 ```
 
-`--normalize` is off by default on `speak`/`say`, so notification phrases synthesize exactly as before. The tuning flags mirror the library defaults (all on except emoji-strip): `--no-markdown`, `--no-expand-units`, `--no-expand-numbers`, `--no-pauses`, `--tables {drop,csv}`, `--strip-emoji`, `--no-terminal-stops`, `--locale`, and a `--pronunciations FILE` (a JSON `{"written": "spoken"}` map, applied whole-word and case-insensitively).
+`--normalize` is off by default on `speak`/`say`, so notification phrases synthesize exactly as before. The tuning flags mirror the library defaults (all on except emoji-strip): `--no-markdown`, `--no-dev-terms`, `--no-expand-units`, `--no-expand-numbers`, `--no-pauses`, `--tables {drop,csv}`, `--code-blocks {drop,placeholder}`, `--strip-emoji`, `--no-terminal-stops`, `--locale`, and a `--pronunciations FILE` (a JSON `{"written": "spoken"}` map, applied whole-word and case-insensitively).
+
+**Dev-output handling** (on by default; `--no-dev-terms` to disable) covers two things espeak reads badly: acronyms it says as words (`CLI` → "C L I", `AWS`, `URI`, `IAM`, …) and file-line references, which it voices literally as "dot py colon". A `file.ext:line` ref is re-spoken lead-with-the-line: `engine.py:42` → "line 42 of engine py", `cli.py:100-118` → "lines 100 to 118 of cli py", `foo.ts:666:10` → "line 666, column 10 of foo ts". Times, ratios, and versions (`12:30`, `3:1`, `1.2.3`) are left alone.
+
+Fenced code blocks are dropped by default. `--code-blocks placeholder` instead speaks a short stand-in so a skipped block doesn't sound disjointed (ChatGPT-style) — set the wording with `--code-placeholder` (e.g. `--code-blocks placeholder --code-placeholder "you can see the code in the chat history"`); consecutive blocks collapse to one.
 
 Bash completion:
 

{stackvox-0.10.0 → stackvox-0.12.0}/README.md

@@ -69,7 +69,11 @@ stackvox speak --normalize --file post.md       # normalize, then synthesize
 stackvox say   --normalize "**Shipped** 1,198.9 MPG"   # normalize, then send to daemon
 ```
 
-`--normalize` is off by default on `speak`/`say`, so notification phrases synthesize exactly as before. The tuning flags mirror the library defaults (all on except emoji-strip): `--no-markdown`, `--no-expand-units`, `--no-expand-numbers`, `--no-pauses`, `--tables {drop,csv}`, `--strip-emoji`, `--no-terminal-stops`, `--locale`, and a `--pronunciations FILE` (a JSON `{"written": "spoken"}` map, applied whole-word and case-insensitively).
+`--normalize` is off by default on `speak`/`say`, so notification phrases synthesize exactly as before. The tuning flags mirror the library defaults (all on except emoji-strip): `--no-markdown`, `--no-dev-terms`, `--no-expand-units`, `--no-expand-numbers`, `--no-pauses`, `--tables {drop,csv}`, `--code-blocks {drop,placeholder}`, `--strip-emoji`, `--no-terminal-stops`, `--locale`, and a `--pronunciations FILE` (a JSON `{"written": "spoken"}` map, applied whole-word and case-insensitively).
+
+**Dev-output handling** (on by default; `--no-dev-terms` to disable) covers two things espeak reads badly: acronyms it says as words (`CLI` → "C L I", `AWS`, `URI`, `IAM`, …) and file-line references, which it voices literally as "dot py colon". A `file.ext:line` ref is re-spoken lead-with-the-line: `engine.py:42` → "line 42 of engine py", `cli.py:100-118` → "lines 100 to 118 of cli py", `foo.ts:666:10` → "line 666, column 10 of foo ts". Times, ratios, and versions (`12:30`, `3:1`, `1.2.3`) are left alone.
+
+Fenced code blocks are dropped by default. `--code-blocks placeholder` instead speaks a short stand-in so a skipped block doesn't sound disjointed (ChatGPT-style) — set the wording with `--code-placeholder` (e.g. `--code-blocks placeholder --code-placeholder "you can see the code in the chat history"`); consecutive blocks collapse to one.
 
 Bash completion:
 

{stackvox-0.10.0 → stackvox-0.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stackvox"
-version = "0.10.0"
+version = "0.12.0"
 description = "Offline TTS library using Kokoro-82M"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -61,6 +61,14 @@ stackvox = ["py.typed", "data/stackvox-say"]
 line-length = 110
 target-version = "py310"
 
+[tool.ruff.format]
+# Ruff 0.16 began formatting Python code blocks inside Markdown. Ours are
+# illustrative rather than real code, and their layout is deliberate: the
+# `normalize_for_speech` signature in docs/speech-normalization.md aligns its
+# trailing comments into a readable column of flags, which the formatter
+# collapses. Prose is a human call, so keep the formatter to the code.
+exclude = ["*.md"]
+
 [tool.ruff.lint]
 select = [
     "E",   # pycodestyle errors

{stackvox-0.10.0 → stackvox-0.12.0}/stackvox/cli.py

@@ -77,13 +77,17 @@ _stackvox_completion() {
             COMPREPLY=( $(compgen -W "drop csv" -- "$cur") )
             return 0
             ;;
+        --code-blocks)
+            COMPREPLY=( $(compgen -W "drop placeholder" -- "$cur") )
+            return 0
+            ;;
         --locale)
             COMPREPLY=( $(compgen -W "en-GB" -- "$cur") )
             return 0
             ;;
     esac
 
-    local norm_flags="--no-markdown --pronunciations --no-expand-units --no-expand-numbers --no-pauses --tables --strip-emoji --no-terminal-stops --locale"
+    local norm_flags="--no-markdown --no-dev-terms --no-filenames --pronunciations --no-expand-units --no-expand-numbers --no-pauses --tables --code-blocks --code-placeholder --strip-emoji --no-terminal-stops --locale"
 
     case "$subcommand" in
         speak)
@@ -216,6 +220,12 @@ def _add_normalize_args(parser: argparse.ArgumentParser, *, with_switch: bool) -
         action="store_false",
         help="Do not spell out dev acronyms espeak mispronounces (CLI, CI, IDE, AWS, URI, IAM, ...)",
     )
+    parser.add_argument(
+        "--no-filenames",
+        dest="filenames",
+        action="store_false",
+        help="Leave filenames and paths as written (no 'README dot md', no 'line 42 of cli dot py')",
+    )
     parser.add_argument(
         "--no-expand-units",
         dest="expand_units",
@@ -240,6 +250,19 @@ def _add_normalize_args(parser: argparse.ArgumentParser, *, with_switch: bool) -
         default="drop",
         help="How Markdown tables are voiced (default: drop)",
     )
+    parser.add_argument(
+        "--code-blocks",
+        dest="code_blocks",
+        choices=["drop", "placeholder"],
+        default="drop",
+        help="How fenced code blocks are voiced (default: drop)",
+    )
+    parser.add_argument(
+        "--code-placeholder",
+        dest="code_placeholder",
+        default="Code block.",
+        help='Spoken stand-in for a code block when --code-blocks placeholder (default: "Code block.")',
+    )
     parser.add_argument(
         "--strip-emoji", dest="strip_emoji", action="store_true", help="Remove emoji before speaking"
     )
@@ -277,10 +300,13 @@ def _normalize_kwargs(args: argparse.Namespace) -> dict:
         "markdown": args.markdown,
         "pronunciations": _load_pronunciations(args.pronunciations),
         "dev_terms": args.dev_terms,
+        "filenames": args.filenames,
         "expand_units": args.expand_units,
         "expand_numbers": args.expand_numbers,
         "pauses": args.pauses,
         "tables": args.tables,
+        "code_blocks": args.code_blocks,
+        "code_placeholder": args.code_placeholder,
         "strip_emoji": args.strip_emoji,
         "terminal_stops": args.terminal_stops,
         "locale": args.locale,
@@ -406,12 +432,21 @@ def _cmd_status(_: argparse.Namespace) -> int:
         rc = 0
         # The running daemon can lag the installed package if it wasn't restarted
         # after an upgrade — surface that skew instead of trusting it blindly.
+        # Only a daemon that is genuinely BEHIND wants restarting; a newer one
+        # means the client just run is the older install (a checkout alongside a
+        # global one), and restarting would downgrade what's serving.
         got, running_version = daemon.version()
         if got and running_version != installed:
-            print(
-                f"daemon running {running_version}, but {installed} is installed "
-                f"— restart the daemon (stackvox stop; stackvox serve) to pick it up"
-            )
+            if updates._is_newer(installed, running_version):
+                print(
+                    f"daemon running {running_version}, but {installed} is installed "
+                    f"— restart the daemon (stackvox stop; stackvox serve) to pick it up"
+                )
+            else:
+                print(
+                    f"daemon running {running_version} is newer than the {installed} client "
+                    f"you just ran; no restart needed"
+                )
     else:
         print("stopped")
         rc = 1

{stackvox-0.10.0 → stackvox-0.12.0}/stackvox/daemon.py

@@ -26,6 +26,7 @@ import socket
 import socketserver
 import sys
 import threading
+import time
 from typing import Any
 
 import sounddevice as sd
@@ -42,6 +43,10 @@ MAX_QUEUE = 2
 WORKER_POLL_SECONDS = 0.5
 CLIENT_TIMEOUT_SECONDS = 1.0
 PING_TIMEOUT_SECONDS = 0.5
+# How long `stop` waits for the daemon process to actually exit after it has
+# acknowledged the request, and how often it re-checks.
+STOP_TIMEOUT_SECONDS = 5.0
+STOP_POLL_SECONDS = 0.05
 RECV_BYTES = 1024
 
 
@@ -273,14 +278,19 @@ def _pid_alive(pid: int) -> bool:
         return False
 
 
-def is_running() -> bool:
+def _read_pid() -> int | None:
+    """The pid recorded in the pid file, or None if absent or unparseable."""
     if not PID_PATH.exists():
-        return False
+        return None
     try:
-        pid = int(PID_PATH.read_text().strip())
-    except ValueError:
-        return False
-    return _pid_alive(pid)
+        return int(PID_PATH.read_text().strip())
+    except (ValueError, OSError):
+        return None
+
+
+def is_running() -> bool:
+    pid = _read_pid()
+    return pid is not None and _pid_alive(pid)
 
 
 def _check_for_update_async() -> None:
@@ -359,8 +369,29 @@ def say(
     return send(req)
 
 
-def stop() -> tuple[bool, str]:
-    return send({"command": "stop"})
+def stop(timeout: float = STOP_TIMEOUT_SECONDS) -> tuple[bool, str]:
+    """Shut the daemon down and wait until the process has actually gone.
+
+    The daemon acknowledges the request and only then unwinds `serve_forever`
+    and removes its pid file, so returning on the ack alone made
+    `stackvox stop && stackvox serve` race: `serve` still saw a live pid, refused
+    to start, and the shutdown then completed, leaving nothing running at all.
+    Reporting success before the process has exited makes that sequence, the one
+    `status` recommends, silently useless.
+    """
+    pid = _read_pid()
+    ok, resp = send({"command": "stop"})
+    if not ok or pid is None:
+        # Nothing acknowledged, or no pid to watch: the caller's own
+        # `is_running` check is as good as it gets.
+        return ok, resp
+    deadline = time.monotonic() + timeout
+    while True:
+        if not _pid_alive(pid):
+            return True, resp
+        if time.monotonic() >= deadline:
+            return False, f"daemon acknowledged stop but pid {pid} is still alive after {timeout:g}s"
+        time.sleep(STOP_POLL_SECONDS)
 
 
 def cancel() -> tuple[bool, str]: