Skip to content

migration_helpers

The community/migration_helpers directory is designed to handle the transition of user configuration and data files from legacy CSV formats to the newer, native .talon-list format. This modernization improves Talon's performance and parsing reliability.

CSV to Talon List Migration

The logic for this process is self-contained in migration_helpers.py.

How it Works

The conversion pipeline automatically detects old configuration CSVs, translates their content, writes the new .talon-list files, and renames the legacy files to prevent redundant runs while preserving them as backups.

The system is built around several key components:

  1. CSVData Configuration Tracker: A dataclass that maps each target CSV file to its expected output .talon-list path. It maintains properties such as:
  2. Whether the first line is a header.
  3. Whether the spoken form or value appears first in the CSV.

  4. Custom hooks for processing values or adding dynamic headers (e.g., appending the local hostname to system paths).

  5. Built-in Migrations: The helper is pre-configured with a list of core community CSV configurations to migrate, including:

  6. Git arguments and commands (git_arguments.csv, git_commands.csv)
  7. Vocabulary additions (additional_words.csv)
  8. Key alphabet mappings (alphabet.csv)
  9. System paths, search engines, unix utilities, and websites

  10. Emojis, emoticons, and kaomojis

  11. Format Translation (convert_csv_to_talonlist): This function parses a 1- or 2-column CSV file into the standard Talon list structure:

  12. It skips empty lines, whitespace-only rows, and comments (starting with #).
  13. It maps the columns to spoken_form: value syntax.

  14. It automatically handles string representation formatting (using repr) if values contain quotes or non-printable characters, ensuring syntactically valid .talon-list outputs.

  15. File Operations and Safety (convert_files): To prevent data loss:

  16. If a target .talon-list file already exists, it is backed up with a .bak suffix.
  17. After a successful migration, the original CSV is renamed to .csv-converted-to-talon-list instead of being deleted immediately, allowing you to verify the migration manually.

Startup Execution and Actions

The script integrates directly into Talon's lifecycle and action system:

  • Automatic Migration: On startup, app.register("ready", on_ready) attempts to run the migrations automatically. If Talon's core loader encounters a known timing issue where the action isn't fully registered at boot, a notification is displayed prompting you to restart.
  • Declarative Actions: The module exposes two Talon actions:
  • user.migrate_known_csv_files(): Triggers the standard migration pipeline.
  • user.migrate_custom_csv(...): Allows you to programmatically trigger migrations for custom, user-defined CSV structures outside of the default community set.