wordflow-cli 0.1.4__py3-none-any.whl

wordflow/data/default_config.toml

@@ -0,0 +1,103 @@
+# ==============================================================================
+# Configuration for wordflow CLI
+# Default Location: ~/.config/wordflow/config.toml
+# ==============================================================================
+# ------------------------------------------------------------------------------
+[global]
+# ISO 639-1 language codes (e.g., "en", "nl", "fr", "es")
+# only exception is chinese: you can choose between zh-cn and zh-tw for simplified or traditional translation
+# full list at: https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes
+source_language = "auto" # translate from
+target_language = "en" # translate to
+
+enable_notifications = true # Send system notifications
+
+# ------------------------------------------------------------------------------
+# DEFAULT ANKI CONFIGURATION
+# Used by default for all languages unless language-based overrides are specified 
+# ------------------------------------------------------------------------------
+[anki]
+[anki.default]
+# default AnkiConnect URL
+url = "http://localhost:8765"
+
+# Target deck name. 
+# Supports dynamic placeholders: {source_language}, {target_language}
+# Example: "Languages::{source_language}" creates cards in the deck: "Languages::es" if 'es' is your source_language
+deck = "Languages::{source_language}"
+
+# The name of the note model in Anki
+card_model = "wordflow cloze"
+
+# Map your personal field names 
+#field_names = ["front", "translation", "additional notes"]
+
+# Allow duplicate cards if the same word/cloze already exists in the deck?
+allow_duplicates = false
+
+# Default tags automatically attached to every card added by wordflow
+tags = ["wordflow", "auto-generated"]
+
+# Audio: choose between none|word|sentence|both.
+# Adds automatic audio recordings of the selection
+audio_mode = "sentence"
+# Dictionnary url
+# if a dict_url scheme is specified, it will add a hyperlink to the cloze field
+# dynamic placeholders are: {source_language} {target_language} {word}
+# examples:
+# dict_url=https://context.reverso.net/translation/{source_language}-{target_language}/{word}
+# dict_url=https://en.wiktionary.org/wiki/{word}
+dict_url = "https://glosbe.com/{source_language}/{target_language}/{word}"
+
+# feel free to tweak those values if you use these fields
+max_alternates = 3
+max_definitions = 2
+max_synonyms = 2
+max_examples = 1
+# ------------------------------------------------------------------------------
+# FIELD MAPPINGS
+# ------------------------------------------------------------------------------
+# Map your personal Anki field names (left) to Wordflow data placeholders (right).
+# You can combine multiple placeholders and use HTML tags like <br> or <b>.
+# missing fields are automatically left blank
+#
+# Available placeholders:
+# {cloze}         - The sentence with the {{c1::word}} deletion
+# {translation}   - The translation of the full sentence
+# {source_word}          - The isolated highlighted word
+# {word_audio}
+# {sentence_audio}
+# {sentence_phonetic} - Pinyin / Romaji / Phonetics (if available)
+# {word_phonetic} - Pinyin / Romaji / Phonetics (if available)
+# {alternates}    - Alternative translations of the word (if available)
+# {definitions}   - Dictionary definitions of the word  (if available)
+# {synonyms}      - Synonyms (if available)
+# {examples}      - Example sentences containing the word (if available)
+[anki.default.fields]
+"Sentence" = "{cloze}"
+"Translation" = "{translation}"
+"Audio" = "{word_audio} &nbsp;&nbsp;&nbsp; {sentence_audio}"
+"Phonetics" = "{word_phonetic} &nbsp;&nbsp;&nbsp; {sentence_phonetic}"
+"Definitions" = "{definitions}"
+"Synonyms" = "{synonyms}"
+"Alternates" = "{alternates}"
+"Examples" = "{examples}"
+# ------------------------------------------------------------------------------
+# LANGUAGE-SPECIFIC OVERRIDES
+# Triggered when the source language is detected, or when passing -l/--lang <language_iso_code>
+# use it to change the deck, card model, fields, etc. dynamically based on detected language
+# ------------------------------------------------------------------------------
+
+# Override for Chinese (-l zh-cn)
+[anki.zh-cn]
+deck = "Languages::Chinese"
+
+# Override for Dutch (-l nl)
+[anki.nl]
+deck = "Languages::Nederlands"
+
+[anki.es]
+# experimental: change the accent by changing the top-level domain of the tts request. Please refer to https://gtts.readthedocs.io/en/latest/module.html#localized-accents for more info
+audio_accent = "com.mx"
+
+

wordflow/data/logo.txt

@@ -0,0 +1,11 @@
+$$\      $$\                           $$\       $$$$$$$$\ $$\                         
+$$ | $\  $$ |                          $$ |      $$  _____|$$ |                        
+$$ |$$$\ $$ | $$$$$$\   $$$$$$\   $$$$$$$ |      $$ |      $$ | $$$$$$\  $$\  $$\  $$\ 
+$$ $$ $$\$$ |$$  __$$\ $$  __$$\ $$  __$$ |      $$$$$\    $$ |$$  __$$\ $$ | $$ | $$ |
+$$$$  _$$$$ |$$ /  $$ |$$ |  \__|$$ /  $$ |      $$  __|   $$ |$$ /  $$ |$$ | $$ | $$ |
+$$$  / \$$$ |$$ |  $$ |$$ |      $$ |  $$ |      $$ |      $$ |$$ |  $$ |$$ | $$ | $$ |
+$$  /   \$$ |\$$$$$$  |$$ |      \$$$$$$$ |      $$ |      $$ |\$$$$$$  |\$$$$$\$$$$  |
+\__/     \__| \______/ \__|       \_______|      \__|      \__| \______/  \_____\____/ 
+                                                                                       
+                                                                                       
+                                                                                       

wordflow/data/logo2.txt

@@ -0,0 +1,6 @@
+ _       __               __   ________             
+| |     / /___  _________/ /  / ____/ /___ _      __
+| | /| / / __ \/ ___/ __  /  / /_  / / __ \ | /| / /
+| |/ |/ / /_/ / /  / /_/ /  / __/ / / /_/ / |/ |/ / 
+|__/|__/\____/_/   \__,_/  /_/   /_/\____/|__/|__/  
+                                                    

wordflow/my_classes.py

@@ -0,0 +1,38 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class AnkiConfig:
+    url: str
+    deck: str
+    card_model: str
+    tags: list[str]
+    dict_url: str | None
+    allow_duplicates: bool
+    fields: dict
+    audio_mode: str = "none"
+    audio_accent: str = "com"
+    max_synonyms: int = 3
+    max_alternates: int = 3
+    max_definitions: int = 2
+    max_examples: int = 1
+
+
+@dataclass
+class GlobalConfig:
+    source_language: str
+    target_language: str
+    enable_notifications: bool = True
+
+
+@dataclass
+class TranslationData:
+    source_data: str
+    translated_data: str
+    source_language: str
+    target_language: str
+    phonetic: str | None
+    alternate_translations: list[str] | None
+    synonyms: list[str] | None
+    definitions: list[str] | None
+    examples: list[str] | None

wordflow/notifications.py

@@ -0,0 +1,77 @@
+import subprocess
+import shutil
+import sys
+
+from wordflow.clipboard import copy_to_clipboard
+
+
+def notify(
+    title: str,
+    message: str,
+    urgency: str = "normal",
+    timeout: int = 5000,
+    enable_notifications=True,
+    copy_output_to_clipboard=False,
+):
+    """
+    Sends a Linux desktop notification using notify-send, or simply prints message to terminal
+    """
+    if not enable_notifications:
+        print(title, "\n", message)
+        return
+
+    # Check if notify-send is installed on the user's system
+    if not shutil.which("notify-send"):
+        print(
+            f"[Warning] 'notify-send' is not installed. Missing notification: {title}",
+            file=sys.stderr,
+        )
+        return
+
+    try:
+        if not copy_output_to_clipboard:
+            subprocess.run(
+                [
+                    "notify-send",
+                    "-a",
+                    "Wordflow",  # App name shown in notification center
+                    "-u",
+                    urgency,  # Urgency: low, normal, critical
+                    "-t",
+                    str(timeout),  # Timeout in milliseconds
+                    title,
+                    message,
+                ],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+        else:
+            process = subprocess.run(
+                [
+                    "notify-send",
+                    "-a",
+                    "Wordflow",
+                    "--action=default=Copy",
+                    "--wait",
+                    "-u",
+                    urgency,
+                    "-t",
+                    str(timeout),
+                    title,
+                    message,
+                ],
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            if process.stdout.strip() == "default":
+                # Push the translation to the Wayland clipboard
+                copy_to_clipboard(message)
+
+    except subprocess.CalledProcessError as e:
+        print(
+            f"[Warning] Notification daemon error: {e.stderr.strip()}", file=sys.stderr
+        )
+    except Exception as e:
+        print(f"[Warning] Failed to send notification '{title}': {e}", file=sys.stderr)

wordflow/text_to_speech.py

@@ -0,0 +1,49 @@
+import base64
+import requests
+
+
+class AudioError(Exception):
+    """Custom exception raised when TTS generation fails."""
+
+    pass
+
+
+def get_audio(text: str, language: str, accent: str = ""):
+    """
+    Fetches TTS audio directly from Google's widget API.
+    Returns a base64 UTF-8 encoded string ready for AnkiConnect.
+
+    :param text: The text to be spoken.
+    :param source_language: ISO code (e.g., 'en', 'fr', 'zh').
+    :param accent: Optional TLD (e.g., 'co.uk', 'com.au', 'ca') to change the accent.
+    """
+    text_to_speak = text.strip()
+    if not text_to_speak:
+        return ""
+    # Safety mechanism: Google's TTS endpoint has a strict 200-character limit.
+    # Truncate to prevent HTTP 400 Bad Request errors on massive clipboard copies.
+    if len(text_to_speak) > 200:
+        text_to_speak = text_to_speak[:200]
+    # Accent trick
+    tld = accent.strip() if accent else "com"
+    url = f"https://translate.google.{tld}/translate_tts"
+    params = {
+        "ie": "UTF-8",
+        "q": text_to_speak,
+        "tl": language,
+        "client": "tw-ob",  # Bypasses the token generator
+    }
+
+    headers = {"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"}
+    try:
+        response = requests.get(url, params=params, headers=headers, timeout=5)
+        response.raise_for_status()
+
+        audio_bytes = response.content
+
+        audio_b64 = base64.b64encode(audio_bytes).decode("utf-8")
+
+        return audio_b64
+
+    except requests.RequestException as e:
+        raise AudioError(f"Failed to fetch audio from Google TTS: {str(e)}")

wordflow/translator.py

@@ -0,0 +1,170 @@
+import requests
+from time import sleep
+
+from wordflow.my_classes import TranslationData
+
+
+class TranslationError(Exception):
+    """Custom exception raised when translation fails to prevent bad Anki cards."""
+
+    pass
+
+
+def normalize_lang_code(google_code: str) -> str:
+    """Converts Google's legacy or dialect-specific codes into ISO 639-1."""
+    if not google_code:
+        return ""
+
+    code = google_code.lower()
+
+    legacy_map = {
+        "iw": "he",  # Hebrew
+        "in": "id",  # Indonesian
+        "jw": "jv",  # Javanese
+        "ji": "yi",  # Yiddish
+    }
+    if code in legacy_map:
+        return legacy_map[code]
+
+    if code in ["zh-cn", "zh-tw"]:
+        return code
+
+    # 2. Strip regional subtags (e.g., 'zh-cn' -> 'zh', 'en-us' -> 'en')
+    if "-" in code:
+        code = code.split("-")[0]
+
+    return code
+
+
+def translate(
+    text: str,
+    source_language: str = "auto",
+    target_language: str = "en",
+    max_retries: int = 3,
+) -> TranslationData:
+    """
+    Takes text in any language and translates it into target_language.
+    Returns a dictionnary containing the translation, source language used, and additional info in case of singe word translation: pronounciation, alternate translations, definition, synonyms, examples
+    """
+    text_to_translate = text.strip()
+    if not text_to_translate:
+        raise TranslationError("No text was provided for translation.")
+
+    url = "https://translate.googleapis.com/translate_a/single"
+    params = {
+        "client": "gtx",  # The magical bypass client
+        "sl": source_language,  # (auto is supported)
+        "tl": target_language,
+        "q": text,  # The text to translate
+        "dt": [
+            "t",
+            "bd",
+            "rm",
+            "md",
+            "ss",
+            "ex",
+        ],  # Request the "translation", pronounciation, alternate translations, definition, synonyms, and examples
+    }
+    headers = {"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"}
+
+    last_error = None
+
+    for _ in range(max_retries):
+        try:
+            response = requests.get(url, params=params, headers=headers, timeout=5)
+            # FAIL FAST: If Google rate-limits, abort instantly to avoid extending the ban.
+            if response.status_code == 429:
+                raise TranslationError(
+                    "Google temporarily rate-limited your IP (HTTP 429). Please wait a few minutes."
+                )
+            # other errors
+            response.raise_for_status()
+
+            data = parse_translation_data(response.json())
+            translation_data = TranslationData(
+                source_data=text,
+                translated_data=data["translation"],
+                source_language=data["source_language"],
+                target_language=target_language,
+                phonetic=data.get("phonetic"),
+                alternate_translations=data.get("alternates", ""),
+                synonyms=data.get("synonyms"),
+                definitions=data.get("definitions"),
+                examples=data.get("examples"),
+            )
+            # DEBUG
+            print("json data: ", response.json())
+            print("translation data: ", translation_data)
+            return translation_data
+
+        except requests.RequestException as e:
+            last_error = e
+            sleep(1)  # wait ane retry
+
+    raise TranslationError(f"Failed to translate. Last error: {last_error}")
+
+
+def parse_translation_data(data) -> dict:
+    # parse TRANSLATION
+    translation = "".join([sentence[0] for sentence in data[0] if sentence[0]])
+    # parse PHONETIC
+    phonetic = ""
+    for item in data[0]:
+        # Romanizations are placed in the 3rd index of a specific sub-array
+        if len(item) > 3 and item[3]:
+            phonetic = item[3]
+            break
+    # 3. parse DICTIONARY (Alternate translations)
+    # data[1] exists if it's a single word and dt=bd was requested
+    alternates = []
+    if len(data) > 1 and data[1]:
+        for pos_group in data[1]:
+            # pos_group[0] is the part of speech (e.g., "noun")
+            # pos_group[1] is a list of translated words
+            if len(pos_group) > 1:
+                alternates.extend(pos_group[1])
+    # SOURCE LANGUAGE
+    detected_source_language = data[2]
+    iso_source_language = normalize_lang_code(detected_source_language)
+
+    definitions = []
+    synonyms = []
+    examples = []
+    # 4. parse SYNONYMS
+    ## Located at data[11]. Structure: [ ["noun", [ [ ["syn1", "syn2"], "id" ] ] ], ... ]
+    if len(data) > 11 and data[11]:
+        for pos_group in data[11]:
+            if len(pos_group) > 1 and isinstance(pos_group[1], list):
+                for entry in pos_group[1]:
+                    if (
+                        isinstance(entry, list)
+                        and len(entry) > 0
+                        and isinstance(entry[0], list)
+                    ):
+                        synonyms.extend(entry[0])
+
+    # 5. parse DEFINITIONS
+    # Located at data[12]. Structure: [ ["noun", [ ["definition1", "id", "example"], ... ] ], ... ]
+    if len(data) > 12 and data[12]:
+        for pos_group in data[12]:
+            if len(pos_group) > 1 and isinstance(pos_group[1], list):
+                for entry in pos_group[1]:
+                    if isinstance(entry, list) and len(entry) > 0:
+                        definitions.append(entry[0])
+
+    # 6. parse EXAMPLES
+    # Located at data[13]. Structure: [ [ ["example 1 with <b>tags</b>", ...], ... ] ]
+    if len(data) > 13 and data[13]:
+        if isinstance(data[13], list) and len(data[13]) > 0:
+            for ex_group in data[13][0]:
+                if isinstance(ex_group, list) and len(ex_group) > 0:
+                    examples.append(str(ex_group[0]))
+    return {
+        "translation": translation,
+        "phonetic": phonetic,
+        "alternates": list(set(alternates)),
+        "definitions": definitions,
+        "synonyms": list(set(synonyms)),
+        "examples": examples,
+        "source_language": iso_source_language,
+    }

wordflow/wizard.py

@@ -0,0 +1,191 @@
+import os
+from pathlib import Path
+from importlib.resources import files
+
+
+def _prompt(text: str, default: str) -> str:
+    """Helper to prompt for a string with a fallback default."""
+    ans = input(f"{text} [{default}]: ").strip()
+    return ans if ans else default
+
+
+def _prompt_bool(text: str, default: bool) -> bool:
+    """Helper to prompt for a boolean (y/n)."""
+    default_str = "Y/n" if default else "y/N"
+    ans = input(f"{text} [{default_str}]: ").strip().lower()
+    if not ans:
+        return default
+    return ans in ("y", "yes", "true")
+
+
+def _prompt_int(text: str, default: int) -> int:
+    """Helper to prompt for an integer."""
+    while True:
+        ans = input(f"{text} [{default}]: ").strip()
+        if not ans:
+            return default
+        if ans.isdigit():
+            return int(ans)
+        print("[-] Invalid input. Please type a valid number.\n")
+
+
+def _prompt_list(text: str, default: list[str]) -> list[str]:
+    """Helper to prompt for a comma-separated list."""
+    default_str = ", ".join(default)
+    ans = input(f"{text} [{default_str}]: ").strip()
+    if not ans:
+        return default
+    return [item.strip() for item in ans.split(",") if item.strip()]
+
+
+def _prompt_numbered_choice(text: str, choices: list[str], default: str) -> str:
+    """Prompts the user to choose from a numbered list of options."""
+    print(f"{text} [Default: {default}]")
+
+    for i, choice in enumerate(choices, 1):
+        print(f"  {i}. {choice}")
+
+    while True:
+        ans = input("Select a number (or press ENTER for default): ").strip()
+
+        if not ans:
+            return default
+
+        if ans.isdigit():
+            idx = int(ans)
+            if 1 <= idx <= len(choices):
+                return choices[idx - 1]
+
+        for choice in choices:
+            if ans.lower() == choice.lower():
+                return choice
+
+        print(
+            f"[-] Invalid input. Please type a number between 1 and {len(choices)}.\n"
+        )
+
+
+def _display_ascii_art():
+    """Attempts to load and print the ASCII art logo from the package data."""
+    try:
+        art = files("wordflow").joinpath("data", "logo.txt").read_text(encoding="utf-8")
+        print(f"\033[94m{art}\033[0m")
+    except Exception:
+        pass
+
+
+def launch_wizard() -> dict:
+    """
+    Launches an interactive command-line wizard to configure Wordflow.
+    Returns a dictionary structured for the config.toml file.
+    """
+    config_path = Path(os.path.expanduser("~/.config/wordflow/config.toml"))
+
+    _display_ascii_art()
+    print("=" * 60)
+    print(" Welcome to the Wordflow Setup Wizard!")
+    print(" This will generate your configuration file at:")
+    print(f" {config_path}")
+    print(" Press ENTER to accept the [default] values.")
+    print("=" * 60 + "\n")
+
+    # --- GLOBAL ---
+    print("--- 1. Language & Global Settings ---")
+    source_language = _prompt(
+        "Source language (translate from) [auto, en, zh-cn...]", "auto"
+    )
+    target_language = _prompt("Target language (translate to) [en, fr, nl...]", "en")
+    enable_notifs = _prompt_bool("Enable desktop notifications?", True)
+    print()
+
+    # --- ANKI ---
+    print("--- 2. Anki Settings ---")
+    print("Make sure Anki is open with AnkiConnect installed.")
+    anki_url = _prompt("AnkiConnect URL", "http://localhost:8765")
+    deck = _prompt(
+        "Default Deck name (use {source_language} for dynamic)",
+        "Languages::{source_language}",
+    )
+    card_model = _prompt("Default Card Model name", "wordflow cloze")
+
+    # Inform the user about the new dictionary-based field layout instead of asking them to type it
+    print(
+        "\n -> Wordflow will automatically configure a rich 8-field layout (Sentence, Translation, Audio, Dictionary, etc.)."
+    )
+    print(
+        " -> You can easily customize these mappings or add HTML later in the config file.\n"
+    )
+
+    tags = _prompt_list(
+        "Default tags to apply to cards", ["wordflow", "auto-generated"]
+    )
+
+    allow_duplicates = _prompt_bool("Allow duplicate cards?", False)
+
+    audio_mode = _prompt_numbered_choice(
+        "Audio generation mode", ["none", "word", "sentence", "both"], "sentence"
+    )
+
+    add_dic_url = _prompt_bool(
+        "Add automatic dictionary hyperlinks to flashcards?", False
+    )
+    if add_dic_url:
+        dict_url = _prompt(
+            "Dictionary URL. Supported dynamic tags: {source_language}, {target_language}, {word}",
+            "https://glosbe.com/{source_language}/{target_language}/{word}",
+        )
+    else:
+        dict_url = ""
+
+    # --- DICTIONARY DATA ---
+    print("--- 3. Dictionary & Card Richness ---")
+    print("Set the maximum number of items to display on your cards if available.")
+    max_alternates = _prompt_int("Max alternate translations", 3)
+    max_definitions = _prompt_int("Max monolingual definitions", 2)
+    max_synonyms = _prompt_int("Max synonyms", 2)
+    max_examples = _prompt_int("Max example sentences", 1)
+
+    print("\n" + "=" * 60)
+    print(" Configuration complete!")
+    print(
+        " Note: You can tweak dictionary limits, field mappings, and language-specific"
+    )
+    print(f" overrides by editing {config_path} manually later.")
+    print("=" * 60)
+
+    # Construct the dictionary perfectly matching the new TOML schema
+    return {
+        "global": {
+            "source_language": source_language,
+            "target_language": target_language,
+            "enable_notifications": enable_notifs,
+        },
+        "anki": {
+            "default": {
+                "url": anki_url,
+                "deck": deck,
+                "card_model": card_model,
+                "allow_duplicates": allow_duplicates,
+                "tags": tags,
+                "audio_mode": audio_mode,
+                "dict_url": dict_url,
+                "max_alternates": 3,
+                "max_definitions": 2,
+                "max_synonyms": 2,
+                "max_examples": 1,
+                "fields": {
+                    "Sentence": "{cloze}",
+                    "Translation": "{translation}",
+                    "Audio": "{word_audio} &nbsp;&nbsp;&nbsp; {sentence_audio}",
+                    "Phonetics": "{word_phonetic} &nbsp;&nbsp;&nbsp; {sentence_phonetic}",
+                    "Definitions": "{definitions}",
+                    "Synonyms": "{synonyms}",
+                    "Alternates": "{alternates}",
+                    "Examples": "{examples}",
+                },
+            },
+            # Examples of override
+            "nl": {"deck": "Languages::Nederlands"},
+            "es": {"audio_accent": "com.mx"},
+        },
+    }