wordflow-cli 0.1.4__py3-none-any.whl

wordflow/__init__.py

@@ -0,0 +1 @@
+# Makes the folder an importable package

wordflow/anki_flashcard.py

@@ -0,0 +1,283 @@
+import time
+import requests
+import re
+import urllib.parse
+
+from .text_to_speech import get_audio
+from .my_classes import AnkiConfig, TranslationData
+
+
+class AnkiConfigError(Exception):
+    """Raised if there is an error in the anki configuration"""
+
+
+class AnkiConnectError(Exception):
+    """raised if failure to connect to Anki through AnkiConnect"""
+
+    pass
+
+
+class DuplicateNoteError(Exception):
+    """raised if a duplicate note exists, so no card was created"""
+
+
+def invoke(url: str, action: str, **params):
+    """
+    Standard helper to send actions to AnkiConnect and handle its error format.
+    """
+    payload = {"action": action, "version": 6, "params": params}
+    try:
+        response = requests.post(url, json=payload, timeout=5).json()
+
+        # AnkiConnect returns {"result": ..., "error": ...}
+        if response.get("error"):
+            raise AnkiConnectError(f"AnkiConnect Error: {response['error']}")
+
+        return response.get("result")
+
+    except requests.exceptions.RequestException as e:
+        raise AnkiConnectError(f"Could not reach Anki. Is it open? ({e})")
+
+
+def setup_anki_model(url: str, model_name: str, fields: dict):
+    """
+    Checks if the required Cloze model exists.
+    If it does exist, it verifies the fields match to prevent silent crashes.
+    If not, it creates it.
+    """
+    if not fields:
+        raise ValueError("fields must contain at least one field.")
+
+    existing_models = invoke(url, "modelNames")
+    field_names = list(fields.keys())
+
+    if model_name in existing_models:
+        existing_fields = invoke(url, "modelFieldNames", modelName=model_name)
+
+        if existing_fields != field_names:
+            raise AnkiConfigError(
+                f"\nFATAL: The Anki model '{model_name}' already exists, but its fields do not match your config.toml.\n"
+                f"Anki expects : {existing_fields}\n"
+                f"Config sends : {field_names}\n"
+            )
+        return
+
+    # if wordflow cloze model does not exist, we create it
+    if model_name not in existing_models:
+        css = """
+        .card { font-family: arial; font-size: 20px; text-align: center; color: white; background-color: #282a36; }
+        .cloze { font-weight: bold; color: #ffb86c; }
+        #answer { border-top: 1px solid #6272a4; margin-top: 8px; padding-top: 10px; }
+        .anki-field { margin-top: 12px; }
+        """
+        # front. Works since keys are kept in order in python dict
+        front_anki = "{{cloze:" + field_names[0] + "}}"
+
+        # back
+        back_anki_parts = [f'{front_anki}<div id="answer">']
+        for field in field_names[1:]:
+            # Using Anki conditional rendering
+            # This ensures no whitespace is added if the field is left blank.
+            conditional_render = (
+                "{{#"
+                + field
+                + "}}<div class='anki-field'>{{"
+                + field
+                + "}}</div>{{/"
+                + field
+                + "}}"
+            )
+            back_anki_parts.append(conditional_render)
+
+        back_anki_parts.append("</div>")
+        back_anki = "".join(back_anki_parts)
+
+        invoke(
+            url,
+            "createModel",
+            modelName=model_name,
+            inOrderFields=field_names,
+            isCloze=True,
+            css=css,
+            cardTemplates=[
+                {
+                    "Name": "Wordflow Cloze",
+                    "Front": front_anki,
+                    "Back": back_anki,
+                }
+            ],
+        )
+
+
+def make_cloze(
+    anki_config: AnkiConfig, sentence_data: TranslationData, word_data: TranslationData
+):
+    """
+    makes a cloze flashcard and sends it to anki through AnkiConnect
+    """
+    # before doing anything, checks that the word is in the sentence
+    if word_data.source_data.lower() not in sentence_data.source_data.lower():
+        raise ValueError(
+            f"Could not find the word '{word_data.source_data}' inside the sentence. Cloze creation failed."
+        )
+
+    # check environment (create card type and deck if non-existing)
+    setup_anki_model(anki_config.url, anki_config.card_model, anki_config.fields)
+
+    # make sure deck exists
+    invoke(anki_config.url, "createDeck", deck=anki_config.deck)
+
+    # Make each field match required instructions in config
+    formatted_anki_fields = process_fields(
+        anki_config=anki_config, sentence_data=sentence_data, word_data=word_data
+    )
+
+    # create payload
+    note = {
+        "deckName": anki_config.deck,
+        "modelName": anki_config.card_model,
+        "fields": formatted_anki_fields,
+        "tags": anki_config.tags,
+        "options": {"allowDuplicate": anki_config.allow_duplicates},
+    }
+
+    try:
+        invoke(anki_config.url, "addNote", note=note)
+    except AnkiConnectError as e:
+        if "duplicate" in str(e).lower():
+            raise DuplicateNoteError(
+                f"A note for '{word_data.source_data}' already exists."
+            )
+        raise e
+    return True
+
+
+def add_audio_to_anki(url: str, text: str, lang_code: str, accent: str):
+    """uses text-to-speech to create an audio of the given text and returns the [sound:...] tag."""
+    # generate unique name for the tag
+    filename = f"wordflow_{int(time.time_ns())}.mp3"
+
+    # generate audio
+    audio = get_audio(text=text, language=lang_code, accent=accent)
+
+    # send anki request
+    payload = {"filename": filename, "data": audio}
+    invoke(url=url, action="storeMediaFile", **payload)
+
+    # return audio tag
+    return f"[sound:{filename}]"
+
+
+def process_fields(
+    anki_config: AnkiConfig, sentence_data: TranslationData, word_data: TranslationData
+) -> dict:
+    """
+    Builds the replacement dictionary, generating audio only if required,
+    and formats the user's custom Anki fields.
+    """
+
+    # 1. LAZY AUDIO
+    all_fields_template = "".join(anki_config.fields.values())
+
+    word_audio_instruction = ""
+    if "{word_audio}" in all_fields_template:
+        tag = add_audio_to_anki(
+            anki_config.url,
+            word_data.source_data,
+            word_data.source_language,
+            anki_config.audio_accent,
+        )
+        word_audio_instruction = (
+            f"<span style='font-size: 15px; color: #8be9fd;'><b>Word:</b> {tag}</span>"
+        )
+
+    sentence_audio_instruction = ""
+    if "{sentence_audio}" in all_fields_template:
+        tag = add_audio_to_anki(
+            anki_config.url,
+            sentence_data.source_data,
+            sentence_data.source_language,
+            anki_config.audio_accent,
+        )
+        sentence_audio_instruction = f"<span style='font-size: 15px; color: #8be9fd;'><b>Sentence:</b> {tag}</span>"
+
+    # 2. CLOZE GENERATION + optionnal dictionary url
+    if anki_config.dict_url:
+        safe_word = urllib.parse.quote(word_data.source_data)
+        final_url = anki_config.dict_url.format(
+            word=safe_word,
+            source_language=word_data.source_language,
+            target_language=word_data.target_language,
+        )
+        linked_word = f'<a href="{final_url}" style="text-decoration: none;">{word_data.source_data}</a>'
+        cloze_tag = "{{c1::" + linked_word + "::" + word_data.translated_data + "}}"
+    else:
+        cloze_tag = (
+            "{{c1::" + word_data.source_data + "::" + word_data.translated_data + "}}"
+        )
+
+    pattern = re.compile(re.escape(word_data.source_data), re.IGNORECASE)
+    cloze_instruction = pattern.sub(cloze_tag, sentence_data.source_data)
+
+    # 3. BUILD THE DICTIONARY
+    def format_labeled_list(data_list, max_items, label, separator=", "):
+        if not data_list:
+            return ""
+        items = separator.join(data_list[:max_items])
+        return f"<b>{label}:</b> {items}"
+
+    format_dict = {
+        # base
+        "cloze": cloze_instruction,
+        "translation": sentence_data.translated_data,
+        "source_word": word_data.source_data,
+        # audio
+        "word_audio": word_audio_instruction,
+        "sentence_audio": sentence_audio_instruction,
+        # phonetic
+        "sentence_phonetic": format_labeled_list(
+            getattr(sentence_data, "phonetic", ""), 1, "sentence phonetic"
+        ),
+        "word_phonetic": format_labeled_list(
+            getattr(word_data, "phonetic", ""), 1, "word phonetic"
+        ),
+        # other
+        "alternates": format_labeled_list(
+            getattr(word_data, "alternate_translations", None),
+            anki_config.max_alternates,
+            "Alternates",
+        ),
+        "definitions": format_labeled_list(
+            getattr(word_data, "definitions", None),
+            anki_config.max_definitions,
+            "Definitions",
+            separator="<br>&bull; ",
+        ),
+        "synonyms": format_labeled_list(
+            getattr(word_data, "synonyms", None), anki_config.max_synonyms, "Synonyms"
+        ),
+        "examples": format_labeled_list(
+            getattr(word_data, "examples", None),
+            anki_config.max_examples,
+            "Examples",
+            separator="<br>&bull; ",
+        ),
+    }
+
+    # 4. FORMAT FIELDS
+    formatted_anki_fields = {}
+
+    for field_name, field_template in anki_config.fields.items():
+        if not field_template:
+            formatted_anki_fields[field_name] = ""
+            continue
+
+        try:
+            formatted_anki_fields[field_name] = field_template.format(**format_dict)
+        except KeyError as e:
+            raise AnkiConfigError(
+                f"Warning: Unknown placeholder {e} in config field '{field_name}'"
+            )
+
+    print("fields sent to anki: ", formatted_anki_fields)
+    return formatted_anki_fields

wordflow/cli.py

@@ -0,0 +1,115 @@
+import sys
+import argparse
+import traceback
+
+# local modules
+from .configuration import create_config, load_config, print_config
+from .workflows import translate_workflow, cloze_workflow
+from .wizard import launch_wizard
+from .my_classes import GlobalConfig, AnkiConfig
+from .notifications import notify
+
+
+def get_parser():
+    parser = argparse.ArgumentParser(
+        prog="wordflow",
+        description="Automate Anki flashcard creation and text translation directly from your clipboard!",
+        epilog="Run 'wordflow --manual' to read the full detailed documentation.",
+    )
+    group = parser.add_mutually_exclusive_group(required=True)
+
+    group.add_argument(
+        "-t",
+        "--translate",
+        action="store_true",
+        help="Translate the highlighted text and show a notification.",
+    )
+    group.add_argument(
+        "-c",
+        "--cloze",
+        action="store_true",
+        help="Create a cloze flashcard from highlighted text.",
+    )
+    group.add_argument(
+        "-w",
+        "--wizard",
+        action="store_true",
+        help="Launch the interactive configuration wizard.",
+    )
+
+    group.add_argument(
+        "--print_config",
+        action="store_true",
+        help="print current configuration file and path to file",
+    )
+    # Commandline Overrides
+    parser.add_argument(
+        "-sl",
+        "--source_language",
+        type=str,
+        default=None,
+        help="Override the source language used for translation",
+    )
+    parser.add_argument(
+        "-tl",
+        "--target_language",
+        type=str,
+        default=None,
+        help="Override the target language used for translation",
+    )
+    parser.add_argument(
+        "--notify",
+        action=argparse.BooleanOptionalAction,
+        help="Enable or disable notifications (overrides config.toml)",
+    )
+
+    return parser
+
+
+def main():
+
+    # 1. Parse CL arguments
+    parser = get_parser()
+
+    if len(sys.argv) == 1:
+        parser.print_help(sys.stderr)
+        sys.exit(1)
+
+    args = parser.parse_args()
+
+    try:
+        # 2. Handle config and wizard
+        if args.wizard:
+            config = launch_wizard()
+            create_config(config)
+            sys.exit(0)
+        if args.print_config:
+            print_config()
+            sys.exit(0)
+
+        # 3. loads configuration
+        global_config, raw_anki_data = load_config(
+            args.source_language, args.target_language, args.notify
+        )
+
+        # 4. trigger workflow
+        if args.translate:
+            translate_workflow(global_config)
+
+        elif args.cloze:
+            cloze_workflow(global_config, raw_anki_data)
+
+    except KeyboardInterrupt:
+        notify(
+            "Wordflow",
+            "Operation cancelled.",
+            enable_notifications=global_config.enable_notifications,
+        )
+    except Exception as e:
+        print("\n[DEBUG TRACEBACK]:", file=sys.stderr)
+        traceback.print_exc()  # Prints exact file, line number, and call stack
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

wordflow/clipboard.py

@@ -0,0 +1,104 @@
+# Abstraction for Wayland/X11 clipboard reading
+# Checks if the user is on Wayland ($WAYLAND_DISPLAY) or X11 ($XDG_SESSION_TYPE).
+# It then calls the appropriate system tool (wl-paste or xclip) or uses a Python library to return clean, string-formatted text.
+
+import os
+import subprocess
+import shutil
+from time import sleep
+
+
+class ClipboardError(Exception):
+    """raised if the user is missing clipboard dependency"""
+
+    pass
+
+
+class TimeOutError(Exception):
+    """raised if no user input is detected for a while"""
+
+
+def get_text(exclusive_text: str = "") -> str:
+    """
+    gets text from clipboard, waiting for user input.
+    can pass exclusive_text to omit input equal to the excluded text
+    throws timeout and clipboard errors.
+    """
+    for _ in range(10):
+        current_highlight = get_clipboard_content()
+        if current_highlight and current_highlight != exclusive_text:
+            return current_highlight
+        sleep(1)
+    raise TimeOutError
+
+
+def get_clipboard_content() -> str:
+    is_wayland = bool(os.environ.get("WAYLAND_DISPLAY"))
+    if is_wayland:
+        # Ensure wl-clipboard is actually installed
+        if not shutil.which("wl-paste"):
+            raise ClipboardError(
+                "Missing dependency: 'wl-clipboard' is not installed. (e.g., sudo pacman -S wl-clipboard)"
+            )
+        # Try highlighted text first, fall back to standard clipboard
+        try:
+            result = subprocess.run(
+                ["wl-paste", "-p"], capture_output=True, text=True, check=True
+            )
+            if result.stdout.strip():
+                return result.stdout.strip()
+        except subprocess.CalledProcessError:
+            pass
+
+        # Fallback to normal clipboard BLOCKED
+        # try:
+        #     result = subprocess.run(
+        #         ["wl-paste"], capture_output=True, text=True, check=True
+        #     )
+        #     if result.stdout.strip():
+        #         return result.stdout.strip()
+        # except subprocess.CalledProcessError:
+        #     pass  # Standard clipboard is also empty
+
+    else:
+        # X11 approach using xclip
+        if not shutil.which("xclip"):
+            raise ClipboardError(
+                "Missing dependency: 'xclip' is not installed. (e.g., sudo pacman -S xclip)"
+            )
+        try:
+            result = subprocess.run(
+                ["xclip", "-o", "-selection", "primary"],
+                capture_output=True,
+                text=True,
+                check=True,
+            )
+            if result.stdout.strip():
+                return result.stdout.strip()
+        except subprocess.CalledProcessError:
+            pass
+        # # Fallback to standard clipboard BLOCKED
+        # try:
+        #     result = subprocess.run(
+        #         ["xclip", "-o", "-selection", "clipboard"],
+        #         capture_output=True,
+        #         text=True,
+        #         check=True
+        #     )
+        #     if result.stdout.strip():
+        #         return result.stdout.strip()
+        # except subprocess.CalledProcessError:
+        #     pass
+    # blank return otherwise
+    return ""
+    # raise ClipboardError("No text found in primary selection.")
+
+
+def copy_to_clipboard(message: str):
+    """sends a message to store in the clipboard"""
+    if os.environ.get("WAYLAND_DISPLAY"):
+        clipboard_cmd = ["wl-copy"]
+    else:
+        clipboard_cmd = ["xclip", "-selection", "clipboard"]
+    # Push the translation to the clipboard
+    subprocess.run(clipboard_cmd, input=message, text=True, check=True)

wordflow/configuration.py

@@ -0,0 +1,171 @@
+# Reads/writes user settings from ~/.config/
+# if no config file exists, creates a default one
+import tomllib
+from pathlib import Path
+from importlib.resources import files
+import tomli_w
+
+from .my_classes import GlobalConfig, AnkiConfig
+
+
+config_dir = Path.home() / ".config" / "wordflow"
+config_file = config_dir / "config.toml"
+
+
+class ConfigError(Exception):
+    """Custom exception raised when configuration loading fails."""
+
+    pass
+
+
+def print_config():
+    """
+    Reads and prints the current configuration file
+    """
+
+    print("default config path: .config/wordflow/config.toml")
+    try:
+        print(config_file.read_text(encoding="utf-8"))
+    except FileNotFoundError:
+        raise ConfigError(
+            "Error: Could not find config.toml in .config/wordflow. \n",
+            "If this is the first time you run this program, wordflow will automatically create one when called with --translate, --cloze, or --wizard",
+        )
+
+
+def create_config(config_dict: dict | None = None):
+    # create default config
+    if not config_dict:
+        try:
+            default_config = (
+                files("wordflow")
+                .joinpath("data", "default_config.toml")
+                .read_text(encoding="utf-8")
+            )
+        except FileNotFoundError:
+            raise ConfigError(
+                "CRITICAL: Could not find default_config.toml in package data. Try a clean install."
+            )
+
+        config_dir.mkdir(parents=True, exist_ok=True)
+        config_file.write_text(default_config.strip(), encoding="utf-8")
+        return True
+    # else we make a custom config (from the wizard)
+    try:
+        config_dir.mkdir(parents=True, exist_ok=True)
+        with open(config_file, "wb") as f:
+            tomli_w.dump(config_dict, f)
+
+        commented_examples = """
+# ------------------------------------------------------------------------------
+# LANGUAGE-SPECIFIC OVERRIDES (EXAMPLES)
+# ------------------------------------------------------------------------------
+# Uncomment and modify these to change settings dynamically based on the detected language.
+
+# Override for Dutch (-sl nl)
+# [anki.nl]
+# deck = "Languages::Nederlands"
+
+# Override for Spanish (-sl es)
+# [anki.es]
+# audio_accent = "com.mx" # Uses Mexican Spanish pronunciation
+            """
+        with open(config_file, "a", encoding="utf-8") as f:
+            f.write(commented_examples)
+        return True
+
+    except Exception as e:
+        # Fallback error handling if there's a permission issue
+        raise ConfigError(
+            f"\n[-] Critical Error: Failed to write config file. \n Details: {e}"
+        )
+
+
+def load_config(
+    source_language_override: str | None = None,
+    target_language_override: str | None = None,
+    notify: bool | None = None,
+):
+    """
+    reads user config or creates one if there is none
+    returns GlobalConfig, and raw anki data dictionnary
+    """
+
+    # create default config the first time
+    if not config_file.exists():
+        create_config()
+
+    try:
+        with open(config_file, "rb") as f:
+            config = tomllib.load(f)
+
+            global_data = config.get("global", {})
+            global_config = GlobalConfig(
+                source_language=source_language_override
+                or global_data.get("source_language", "auto"),
+                target_language=target_language_override
+                or global_data.get("target_language", "en"),
+                enable_notifications=notify
+                if notify is not None
+                else global_data.get("enable_notifications", True),
+            )
+            raw_anki_data = config.get("anki", {})
+
+            return global_config, raw_anki_data
+
+    except tomllib.TOMLDecodeError as e:
+        # Catch syntax errors
+        raise ConfigError(
+            f"Syntax error in config file ({config_file}):\n  -> {e}\n\nPlease fix the typo, or delete the file to regenerate the defaults."
+        )
+    except PermissionError:
+        raise ConfigError(f"Permission denied: Cannot read {config_file}.")
+
+
+def resolve_anki_config(
+    raw_anki_data: dict, active_language: str | None = None
+) -> AnkiConfig:
+    """
+    Merges [anki.default] with language-specific [anki.<lang>] overrides.
+    Returns a final AnkiConfig class with resolved names.
+    if there is no override, simply returns the default anki config
+    """
+
+    anki_defaults = raw_anki_data.get("default", {})
+    anki_override = raw_anki_data.get(str(active_language), {})
+
+    anki_defaults_fields = anki_defaults.get("fields", {})
+    anki_override_fields = anki_override.get("fields", {})
+
+    anki_config = AnkiConfig(
+        url=anki_override.get("url", anki_defaults.get("url")),
+        deck=anki_override.get(
+            "deck", anki_defaults.get("deck", "Wordflow::{source_language}")
+        ).replace("{source_language}", str(active_language)),
+        card_model=anki_override.get("card_model", anki_defaults.get("card_model")),
+        tags=anki_override.get("tags", anki_defaults.get("tags", "")),
+        allow_duplicates=anki_override.get(
+            "allow_duplicates", anki_defaults.get("allow_duplicates", False)
+        ),
+        dict_url=anki_override.get("dict_url", anki_defaults.get("dict_url", "")),
+        fields=anki_override_fields if anki_override_fields else anki_defaults_fields,
+        audio_mode=anki_override.get(
+            "audio_mode", anki_defaults.get("audio_mode", "none")
+        ),
+        audio_accent=anki_override.get(
+            "audio_accent", anki_defaults.get("audio_accent", "com")
+        ),
+        max_synonyms=anki_override.get(
+            "max_synonyms", anki_defaults.get("max_synonyms")
+        ),
+        max_alternates=anki_override.get(
+            "max_alternates", anki_defaults.get("max_alternates")
+        ),
+        max_definitions=anki_override.get(
+            "max_definitions", anki_defaults.get("max_definitions")
+        ),
+        max_examples=anki_override.get(
+            "max_examples", anki_defaults.get("max_examples")
+        ),
+    )
+    return anki_config