Skip to content

migration_helpers

The community/migration_helpers directory contains a single file, migration_helpers.py. This file provides functionality to convert CSV files into .talon-list files, which are used by Talon to define lists of words or phrases that can be recognized by voice.

Here's a breakdown of how it works:

  • CSVData dataclass: This dataclass is used to define how a specific CSV file should be converted. It contains the following information:

    • name: The name of the Talon list that will be generated.
    • path: The path to the CSV file.
    • newpath: The path where the generated .talon-list file will be created. It can also be a function to dynamically generate the path.
    • is_first_line_header: A boolean that indicates whether the first line of the CSV file is a header that should be skipped.
    • is_spoken_form_first: A boolean that indicates whether the spoken form or value is first in the CSV file.
    • custom_header: An optional function to generate a custom header for the .talon-list file.
    • custom_value_converter: An optional function to convert the value for the generated .talon-list file.

  • supported_csv_files list: This list contains CSVData objects for the CSV files that are automatically migrated by the script. Each entry specifies the location of a CSV file and the corresponding .talon-list that should be generated. For example, user.git_argument in apps/git/git_arguments.csv becomes apps/git/git_argument.talon-list. The user.system_paths list has a lambda which generates a different file name per hostname.

  • convert_csv_to_talonlist(input_csv, config) function: This function takes a csv.reader object and a CSVData object and converts the data from the CSV file to the format expected by .talon-list files. It skips empty lines, lines starting with # and also performs the following:

    • Handles cases where the CSV file has one or two columns.
    • Supports an optional spoken form.
    • Applies custom value converters.
    • Adds a header describing the list.
    • Ensures that non-printable characters are escaped when generating the talon-list.

  • convert_files(csv_files_list) function: This function iterates through all .csv files in the repository, checking them against supported_csv_files. It uses the convert_csv_to_talonlist function to convert the data and writes it to the correct location in a .talon-list file and also renames the .csv file to a .csv-converted-to-talon-list file. It will not overwrite a .talon-list file without making a backup, and will not try to convert CSV files that have been renamed.

  • Actions class: This class defines the migrate_known_csv_files action that can be called from Talon to migrate all known CSV files and a migrate_custom_csv action that can be called for a single custom CSV.

  • on_ready function: This function is called when Talon is ready and will trigger the migration of known CSV files to .talon-list files. If the Talon action is not available yet, it will print a warning to the user.