stackvox 0.10.0__tar.gz → 0.11.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.10.0
+Version: 0.11.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.11.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.11.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "stackvox"
-version = "0.10.0"
+version = "0.11.0"
 description = "Offline TTS library using Kokoro-82M"
 readme = "README.md"
 requires-python = ">=3.10"

{stackvox-0.10.0 → stackvox-0.11.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 --pronunciations --no-expand-units --no-expand-numbers --no-pauses --tables --code-blocks --code-placeholder --strip-emoji --no-terminal-stops --locale"
 
     case "$subcommand" in
         speak)
@@ -240,6 +244,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"
     )
@@ -281,6 +298,8 @@ def _normalize_kwargs(args: argparse.Namespace) -> dict:
         "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,

{stackvox-0.10.0 → stackvox-0.11.0}/stackvox/text.py

@@ -20,6 +20,7 @@ __all__ = [
     "strip_thousands_separators",
     "versions_to_words",
     "decimals_to_words",
+    "speak_file_refs",
     "expand_units",
     "apply_pronunciations",
     "shape_pauses",
@@ -64,6 +65,7 @@ _UNIT_RULES: dict[str, list[tuple[str, str]]] = {
         (r"\s*÷\s*", " divided by "),
         (r"\s*×\s*", " times "),
         (r"\s*=\s*", " equals "),
+        (r"~\s*(?=\d)", "about "),  # ~123 -> "about 123" (else espeak says "tilde 123"); leaves ~/path alone
     ],
 }
 DEFAULT_LOCALE = "en-GB"
@@ -110,6 +112,46 @@ def decimals_to_words(text: str) -> str:
     )
 
 
+# --------------------------------------------------------------------------- #
+# File & line references                                                      #
+# --------------------------------------------------------------------------- #
+# `engine.py:42` reads as "…dot py colon forty two" — the dots and colon get
+# voiced literally. Spoken aloud the line number is the signal and the filename
+# is noise, so lead with "line N of <file>" (how a person actually says it) and
+# soften the path: drop directories to the basename, and voice the dotted name
+# word by word.
+
+_FILE_REF = re.compile(
+    r"(?<!\w)"
+    r"(?:[\w.-]*/)*"  # optional directory segments (dropped — "src/" reads as "slash")
+    r"([A-Za-z0-9_-]+(?:\.[A-Za-z][\w-]*)+)"  # filename with >=1 letter-initial extension
+    r":(\d+)(?:-(\d+))?(?::(\d+))?"  # :line, optional -end (range) or :column
+    r"(?!\w)"
+)
+
+
+def speak_file_refs(text: str) -> str:
+    """Turn ``path/file.ext:line`` refs into spoken "line N of file ext".
+
+    ``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". The
+    ``:line`` suffix is the trigger, so bare times/ratios/verses (``12:30``,
+    ``3:1``, ``John 3:16``) and dotted versions (``1.2.3``) are left untouched —
+    none of them carry a dotted-filename before the colon.
+    """
+
+    def repl(match: re.Match[str]) -> str:
+        basename = match.group(1).replace(".", " ")
+        start, end, column = match.group(2), match.group(3), match.group(4)
+        if end:
+            location = f"lines {start} to {end}"
+        else:
+            location = f"line {start}" + (f", column {column}" if column else "")
+        return f"{location} of {basename}"
+
+    return _FILE_REF.sub(repl, text)
+
+
 # --------------------------------------------------------------------------- #
 # Pronunciations                                                              #
 # --------------------------------------------------------------------------- #
@@ -142,6 +184,13 @@ _DEV_PRONUNCIATIONS: dict[str, str] = {
     "postgresql": "postgres",
     "kubectl": "kube control",
     "stackone": "stack one",  # org name espeak garbles as "stac kone"
+    # "dedupe" glued reads as "de-dup" (short u); split + long "dee" gives "dee doop".
+    # Inflections listed explicitly — apply_pronunciations matches whole words only.
+    "dedupe": "dee dupe",
+    "deduped": "dee duped",
+    "deduping": "dee duping",
+    "dedupes": "dee dupes",
+    "dedup": "dee dupe",
 }
 
 
@@ -189,11 +238,24 @@ def _strip_md_inline(line: str) -> str:
     return line
 
 
-def markdown_to_paragraphs(text: str, *, tables: str = "drop", strip_emoji_flag: bool = False) -> list[str]:
+def markdown_to_paragraphs(
+    text: str,
+    *,
+    tables: str = "drop",
+    strip_emoji_flag: bool = False,
+    code_blocks: str = "drop",
+    code_placeholder: str = "",
+) -> list[str]:
     """Reduce Markdown to a list of speakable paragraphs. Headings and list
     items become their own paragraphs (so each gets its own pause). Tables are
-    dropped or rendered comma-separated per ``tables``."""
-    text = re.sub(r"(?ms)^[ \t]*(```|~~~).*?^[ \t]*\1[ \t]*$", "\n", text)  # fenced code
+    dropped or rendered comma-separated per ``tables``. Fenced code blocks are
+    dropped, or (``code_blocks="placeholder"``) replaced with a spoken
+    ``code_placeholder`` so a silently-skipped block doesn't sound disjointed."""
+    speak_code = code_blocks == "placeholder" and bool(code_placeholder)
+    # A function replacement keeps the placeholder literal (no backref parsing);
+    # blank lines around it make it a standalone paragraph.
+    fenced = f"\n\n{code_placeholder}\n\n" if speak_code else "\n"
+    text = re.sub(r"(?ms)^[ \t]*(```|~~~).*?^[ \t]*\1[ \t]*$", lambda _: fenced, text)  # fenced code
     text = re.sub(r"```+|~~~+", " ", text)  # stray fences
     if strip_emoji_flag:
         text = strip_emoji(text)
@@ -278,6 +340,14 @@ def markdown_to_paragraphs(text: str, *, tables: str = "drop", strip_emoji_flag:
             flush()
 
     flush()
+
+    if speak_code:  # collapse runs of adjacent code blocks into one placeholder
+        collapsed: list[str] = []
+        for para in paragraphs:
+            if para == code_placeholder and collapsed and collapsed[-1] == code_placeholder:
+                continue
+            collapsed.append(para)
+        return collapsed
     return paragraphs
 
 
@@ -290,11 +360,17 @@ def _shape_paragraph(
     text: str,
     *,
     pronunciations: dict[str, str] | None,
+    dev_terms_flag: bool,
     expand_units_flag: bool,
     expand_numbers_flag: bool,
     pauses_flag: bool,
     locale: str,
 ) -> str:
+    # File refs first: it consumes the ":line" digits (so the number stages see a
+    # plain "line 42", not a decimal) and forms the spoken basename before the
+    # dev-term dict runs over it.
+    if dev_terms_flag:
+        text = speak_file_refs(text)
     if expand_numbers_flag:
         text = strip_thousands_separators(text)
     if pauses_flag:
@@ -319,6 +395,8 @@ def normalize_for_speech(
     expand_numbers: bool = True,
     pauses: bool = True,
     tables: str = "drop",
+    code_blocks: str = "drop",
+    code_placeholder: str = "Code block.",
     strip_emoji: bool = False,
     terminal_stops: bool = True,
     locale: str = DEFAULT_LOCALE,
@@ -333,7 +411,13 @@ def normalize_for_speech(
         effective_pronunciations[written.lower()] = spoken
 
     if markdown:
-        paragraphs = markdown_to_paragraphs(text, tables=tables, strip_emoji_flag=strip_emoji)
+        paragraphs = markdown_to_paragraphs(
+            text,
+            tables=tables,
+            strip_emoji_flag=strip_emoji,
+            code_blocks=code_blocks,
+            code_placeholder=code_placeholder,
+        )
     else:
         # `strip_emoji` (the bool kwarg) shadows the module function here, so
         # reach for the underlying pattern directly.
@@ -345,6 +429,7 @@ def normalize_for_speech(
         shaped = _shape_paragraph(
             para,
             pronunciations=effective_pronunciations,
+            dev_terms_flag=dev_terms,
             expand_units_flag=expand_units_flag,
             expand_numbers_flag=expand_numbers_flag,
             pauses_flag=pauses,

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackvox
-Version: 0.10.0
+Version: 0.11.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.11.0}/tests/test_cli.py

@@ -133,6 +133,8 @@ def _norm_ns(text=None, file=None, **overrides):
         expand_numbers=True,
         pauses=True,
         tables="drop",
+        code_blocks="drop",
+        code_placeholder="Code block.",
         strip_emoji=False,
         terminal_stops=True,
         locale="en-GB",
@@ -524,6 +526,26 @@ class TestNormalizeParsing:
         assert cli.main() == 0
         assert paths_handler.called
 
+    def test_code_block_flags_parse(self, mocker):
+        norm = mocker.patch.object(cli, "_cmd_normalize", return_value=0)
+        mocker.patch.object(
+            cli.sys,
+            "argv",
+            [
+                "stackvox",
+                "normalize",
+                "--code-blocks",
+                "placeholder",
+                "--code-placeholder",
+                "see the chat",
+                "hi",
+            ],
+        )
+        assert cli.main() == 0
+        args = norm.call_args.args[0]
+        assert args.code_blocks == "placeholder"
+        assert args.code_placeholder == "see the chat"
+
 
 class TestCmdCancel:
     def test_running_calls_daemon_cancel(self, mocker):

{stackvox-0.10.0 → stackvox-0.11.0}/tests/test_text.py

@@ -8,6 +8,7 @@ from stackvox.text import (
     markdown_to_paragraphs,
     normalize_for_speech,
     shape_pauses,
+    speak_file_refs,
     strip_emoji,
     strip_thousands_separators,
     versions_to_words,
@@ -54,6 +55,44 @@ def test_semver_normalizes_end_to_end():
     assert "0 point 7.0" not in out
 
 
+# --- file & line references ------------------------------------------------
+
+
+def test_file_ref_leads_with_line_then_file():
+    assert speak_file_refs("unifiedAPIv2.service.ts:666") == "line 666 of unifiedAPIv2 service ts"
+
+
+def test_file_ref_drops_directories_to_basename():
+    assert speak_file_refs("Open /abs/path/to/module.py:7.") == "Open line 7 of module py."
+
+
+def test_file_ref_line_range():
+    assert speak_file_refs("cli.py:100-118") == "lines 100 to 118 of cli py"
+
+
+def test_file_ref_line_and_column():
+    assert speak_file_refs("foo.ts:666:10") == "line 666, column 10 of foo ts"
+
+
+def test_file_ref_leaves_times_ratios_verses_untouched():
+    text = "Meet at 12:30, the ratio was 3:1, see John 3:16."
+    assert speak_file_refs(text) == text
+
+
+def test_file_ref_leaves_dotted_versions_untouched():
+    assert speak_file_refs("bump to 1.2.3 and 0.7.0") == "bump to 1.2.3 and 0.7.0"
+
+
+def test_file_ref_normalizes_end_to_end():
+    out = normalize_for_speech("See `engine.py:42` for the fix.", markdown=True)
+    assert out == "See line 42 of engine py for the fix."
+
+
+def test_file_ref_disabled_with_dev_terms():
+    out = normalize_for_speech("See engine.py:42.", markdown=False, dev_terms=False)
+    assert out == "See engine.py:42."
+
+
 # --- units -----------------------------------------------------------------
 
 
@@ -74,6 +113,20 @@ def test_math_symbols():
     assert expand_units("770 ÷ 2 × 3 = 5").strip() == "770 divided by 2 times 3 equals 5"
 
 
+def test_tilde_before_number_is_approximately():
+    assert expand_units("~123") == "about 123"
+    assert expand_units("~ 50 items") == "about 50 items"
+
+
+def test_tilde_not_before_number_is_left_alone():
+    # home dir / approx-equal — not an approximated quantity
+    assert expand_units("~/projects") == "~/projects"
+
+
+def test_tilde_approx_end_to_end_with_decimal():
+    assert normalize_for_speech("took ~1.5 hours", markdown=False) == "took about 1 point 5 hours."
+
+
 def test_unknown_locale_falls_back_to_en_gb():
     assert expand_units("£5", locale="xx-YY") == "5 pounds"
 
@@ -136,6 +189,29 @@ def test_fenced_code_dropped():
     assert markdown_to_paragraphs(md) == ["Before.", "After."]
 
 
+def test_fenced_code_replaced_with_placeholder():
+    md = "Before.\n\n```py\nprint('hi')\n```\n\nAfter."
+    actual = markdown_to_paragraphs(md, code_blocks="placeholder", code_placeholder="see the code")
+    assert actual == ["Before.", "see the code", "After."]
+
+
+def test_consecutive_code_blocks_collapse_to_one_placeholder():
+    md = "```py\na\n```\n\n```py\nb\n```"
+    actual = markdown_to_paragraphs(md, code_blocks="placeholder", code_placeholder="see the code")
+    assert actual == ["see the code"]
+
+
+def test_code_placeholder_spoken_end_to_end():
+    md = "Here is how:\n\n```py\nx = 1\n```\n\nDone."
+    out = normalize_for_speech(md, code_blocks="placeholder", code_placeholder="see the chat history")
+    assert out == "Here is how:\nsee the chat history.\nDone."
+
+
+def test_code_blocks_dropped_by_default_end_to_end():
+    md = "Here is how:\n\n```py\nx = 1\n```\n\nDone."
+    assert normalize_for_speech(md) == "Here is how:\nDone."
+
+
 def test_tables_dropped_by_default():
     md = "| A | B |\n| --- | --- |\n| 1 | 2 |"
     assert markdown_to_paragraphs(md) == []
@@ -244,6 +320,18 @@ def test_dev_terms_leave_correctly_voiced_acronyms_alone():
     assert "API" in out
 
 
+def test_dedupe_respelled_for_speech():
+    assert normalize_for_speech("dedupe the list", markdown=False) == "dee dupe the list."
+    # inflections and case
+    assert "dee duped" in normalize_for_speech("we Deduped it", markdown=False)
+    assert "dee duping" in normalize_for_speech("deduping now", markdown=False)
+
+
+def test_dedupe_does_not_touch_other_words():
+    # whole-word only — must not rewrite the middle of a longer token
+    assert "dee dupe" not in normalize_for_speech("dedupelicated", markdown=False)
+
+
 def test_dev_terms_can_be_disabled():
     assert normalize_for_speech("Use the CLI.", markdown=False, dev_terms=False) == "Use the CLI."