aliased update from file and added completions

Author: oddish3

README.md

@@ -16,6 +16,7 @@ Anki. It does not require Anki to be running at the same time.
 * [Usage](#usage)
 * [Configuration](#configuration)
 * [Zsh completion](#zsh-completion)
+* [fish completion](#fish-completion)
 * [Changelog](#changelog)
 * [Relevant resources](#relevant-resources)
 * [Alternatives](#alternatives)
@@ -173,6 +174,15 @@ Then add the following line to ones `.zshrc` file:
 fpath=($HOME/.local/zsh-functions $fpath)
 ```
 
+## Fish completion
+
+There is also a fish completion file available. To use it, one may symlink or
+copy it to `~/.config/fish/completions/` directory:
+
+```
+ln -s /path/to/apy/completion/apy.fish ~/.config/fish/completions/
+```
+
 ## Changelog
 
 See the [release history on GitHub](https://github.com/lervag/apy/releases).

completion/_apy

@@ -47,7 +47,8 @@ _apy() {
   subcmds=( \
     'add:Add notes interactively from terminal' \
     'add-single:Add a single note from command line arguments' \
-    'add-from-file:Add notes from Markdown file For input file' \
+    'add-from-file:Add notes from Markdown file (alias for update-from-file)' \
+    'update-from-file:Update existing or add new notes from Markdown file' \
     'check-media:Check media' \
     'info:Print some basic statistics' \
     'model:Interact with the models' \
@@ -82,10 +83,12 @@ _apy() {
         '::Fields' \
         $opts_help \
         );;
-    add-from-file)
+    add-from-file|update-from-file)
       opts=( \
         '::Markdown input file:_files -g "*.md"' \
         '(-t --tags)'{-t,--tags}'[Specify tags]:tags:' \
+        '(-d --deck)'{-d,--deck}'[Specify deck]:deck:' \
+        '(-u --update-file)'{-u,--update-file}'[Update original file with note IDs]' \
         $opts_help \
         );;
     info)

completion/apy.fish

@@ -0,0 +1,106 @@
+# Fish shell completion for apy
+# Copy this file to ~/.config/fish/completions/
+
+function __fish_apy_no_subcommand
+    set -l cmd (commandline -opc)
+    if [ (count $cmd) -eq 1 ]
+        return 0
+    end
+    return 1
+end
+
+function __fish_apy_using_command
+    set -l cmd (commandline -opc)
+    if [ (count $cmd) -gt 1 ]
+        if [ $argv[1] = $cmd[2] ]
+            return 0
+        end
+    end
+    return 1
+end
+
+# Main apy command
+complete -f -c apy -n '__fish_apy_no_subcommand' -l help -s h -d 'Show help'
+complete -f -c apy -n '__fish_apy_no_subcommand' -l base-path -s b -d 'Set Anki base directory' -a '(__fish_complete_directories)'
+complete -f -c apy -n '__fish_apy_no_subcommand' -l profile-name -s p -d 'Specify name of Anki profile to use'
+complete -f -c apy -n '__fish_apy_no_subcommand' -l version -s V -d 'Show apy version'
+
+# Subcommands
+complete -f -c apy -n '__fish_apy_no_subcommand' -a add -d 'Add notes interactively from terminal'
+complete -f -c apy -n '__fish_apy_no_subcommand' -a add-single -d 'Add a single note from command line arguments'
+complete -f -c apy -n '__fish_apy_no_subcommand' -a add-from-file -d 'Add notes from Markdown file (alias for update-from-file)'
+complete -f -c apy -n '__fish_apy_no_subcommand' -a update-from-file -d 'Update existing or add new notes from Markdown file'
+complete -f -c apy -n '__fish_apy_no_subcommand' -a check-media -d 'Check media'
+complete -f -c apy -n '__fish_apy_no_subcommand' -a info -d 'Print some basic statistics'
+complete -f -c apy -n '__fish_apy_no_subcommand' -a model -d 'Interact with the models'
+complete -f -c apy -n '__fish_apy_no_subcommand' -a list -d 'Print cards that match query'
+complete -f -c apy -n '__fish_apy_no_subcommand' -a review -d 'Review/Edit notes that match query'
+complete -f -c apy -n '__fish_apy_no_subcommand' -a reposition -d 'Reposition new card with given CID'
+complete -f -c apy -n '__fish_apy_no_subcommand' -a sync -d 'Synchronize collection with AnkiWeb'
+complete -f -c apy -n '__fish_apy_no_subcommand' -a tag -d 'Add or remove tags from notes that match query'
+complete -f -c apy -n '__fish_apy_no_subcommand' -a edit -d 'Edit notes that match query directly'
+complete -f -c apy -n '__fish_apy_no_subcommand' -a backup -d 'Backup Anki database to specified target file'
+
+# add options
+complete -f -c apy -n '__fish_apy_using_command add' -l help -s h -d 'Show help'
+complete -f -c apy -n '__fish_apy_using_command add' -l tags -s t -d 'Specify default tags for new cards'
+complete -f -c apy -n '__fish_apy_using_command add' -l model -s m -d 'Specify default model for new cards'
+complete -f -c apy -n '__fish_apy_using_command add' -l deck -s d -d 'Specify default deck for new cards'
+
+# add-single options
+complete -f -c apy -n '__fish_apy_using_command add-single' -l help -s h -d 'Show help'
+complete -f -c apy -n '__fish_apy_using_command add-single' -l parse-markdown -s p -d 'Parse input as Markdown'
+complete -f -c apy -n '__fish_apy_using_command add-single' -l preset -s s -d 'Specify a preset'
+complete -f -c apy -n '__fish_apy_using_command add-single' -l tags -s t -d 'Specify default tags for new cards'
+complete -f -c apy -n '__fish_apy_using_command add-single' -l model -s m -d 'Specify default model for new cards'
+complete -f -c apy -n '__fish_apy_using_command add-single' -l deck -s d -d 'Specify default deck for new cards'
+
+# add-from-file and update-from-file options
+for cmd in add-from-file update-from-file
+    complete -f -c apy -n "__fish_apy_using_command $cmd" -l help -s h -d 'Show help'
+    complete -f -c apy -n "__fish_apy_using_command $cmd" -l tags -s t -d 'Specify default tags for cards'
+    complete -f -c apy -n "__fish_apy_using_command $cmd" -l deck -s d -d 'Specify default deck for cards'
+    complete -f -c apy -n "__fish_apy_using_command $cmd" -l update-file -s u -d 'Update original file with note IDs'
+    # File argument
+    complete -f -c apy -n "__fish_apy_using_command $cmd" -k -a "(__fish_complete_suffix .md)"
+end
+
+# list options
+complete -f -c apy -n '__fish_apy_using_command list' -l help -s h -d 'Show help'
+complete -f -c apy -n '__fish_apy_using_command list' -l show-answer -s a -d 'Display answer'
+complete -f -c apy -n '__fish_apy_using_command list' -l show-model -s m -d 'Display model'
+complete -f -c apy -n '__fish_apy_using_command list' -l show-cid -s c -d 'Display card ids'
+complete -f -c apy -n '__fish_apy_using_command list' -l show-due -s d -d 'Display card due time in days'
+complete -f -c apy -n '__fish_apy_using_command list' -l show-type -s t -d 'Display card type'
+complete -f -c apy -n '__fish_apy_using_command list' -l show-ease -s e -d 'Display card ease'
+complete -f -c apy -n '__fish_apy_using_command list' -l show-lapses -s l -d 'Display card number of lapses'
+
+# tag options
+complete -f -c apy -n '__fish_apy_using_command tag' -l help -s h -d 'Show help'
+complete -f -c apy -n '__fish_apy_using_command tag' -l add-tags -s a -d 'Add specified tags to matched notes'
+complete -f -c apy -n '__fish_apy_using_command tag' -l remove-tags -s r -d 'Remove specified tags from matched notes'
+complete -f -c apy -n '__fish_apy_using_command tag' -l sort-by-count -s c -d 'When listing tags, sort by note count'
+complete -f -c apy -n '__fish_apy_using_command tag' -l purge -s p -d 'Remove all unused tags'
+
+# review options
+complete -f -c apy -n '__fish_apy_using_command review' -l help -s h -d 'Show help'
+complete -f -c apy -n '__fish_apy_using_command review' -l check-markdown-consistency -s m -d 'Check for Markdown consistency'
+complete -f -c apy -n '__fish_apy_using_command review' -l cmc-range -s n -d 'Number of days backwards to check consistency'
+
+# edit options
+complete -f -c apy -n '__fish_apy_using_command edit' -l help -s h -d 'Show help'
+complete -f -c apy -n '__fish_apy_using_command edit' -l force-multiple -s f -d 'Allow editing multiple notes'
+
+# backup options
+complete -f -c apy -n '__fish_apy_using_command backup' -l help -s h -d 'Show help'
+complete -f -c apy -n '__fish_apy_using_command backup' -l include-media -s m -d 'Include media files in backup'
+complete -f -c apy -n '__fish_apy_using_command backup' -l legacy -s l -d 'Support older Anki versions'
+
+# model subcommands
+complete -f -c apy -n '__fish_apy_using_command model' -a edit-css -d 'Edit the CSS template for the specified model'
+complete -f -c apy -n '__fish_apy_using_command model' -a rename -d 'Rename model from old_name to new_name'
+
+# model edit-css options
+complete -f -c apy -n '__fish_apy_using_command model; and __fish_seen_subcommand_from edit-css' -l help -s h -d 'Show help'
+complete -f -c apy -n '__fish_apy_using_command model; and __fish_seen_subcommand_from edit-css' -l model-name -s m -d 'Specify for which model to edit CSS template'
+complete -f -c apy -n '__fish_apy_using_command model; and __fish_seen_subcommand_from edit-css' -l sync-after -s s -d 'Perform sync after any change'

src/apyanki/cli.py

@@ -133,71 +133,6 @@ def add(tags: str, model_name: str, deck: str) -> None:
         _added_notes_postprocessing(a, notes)
 
 
-@main.command("add-from-file")
-@click.argument("file", type=click.Path(exists=True, dir_okay=False))
-@click.option("-t", "--tags", default="", help="Specify default tags for new cards.")
-@click.option("-d", "--deck", help="Specify default deck for new cards.")
-@click.option(
-    "-u", "--update-file", is_flag=True, help="Update original file with note IDs."
-)
-def add_from_file(file: Path, tags: str, deck: str, update_file: bool) -> None:
-    """Add notes from Markdown file.
-
-    With the --update-file option, the original file will be updated to include
-    note IDs for any new notes added.
-
-    The example below should adequately specify the syntax. Any initial "key: value"
-    pairs specify default values for all the following notes. The following keys are
-    accepted:
-
-    \b
-    * model:    The note model (required)
-    * tags:     The note model (optional)
-    * deck:     Which deck the note should be added to (optional)
-    * markdown: Set to "false" or "no" if apy should not use a markdown converter
-                while converting the input note to an Anki note. (optional)
-    * nid:      The note ID (added automatically with --update-file option)
-
-    Here is the example Markdown input:
-
-        // example.md
-        model: Basic
-        tags: marked
-
-        # Note 1
-        ## Front
-        Question?
-
-        ## Back
-        Answer.
-
-        # Note 2
-        tag: silly-tag
-
-        ## Front
-        Question?
-
-        ## Back
-        Answer
-
-        # Note 3
-        model: NewModel
-        markdown: false (default is true)
-
-        ## NewFront
-        FieldOne
-
-        ## NewBack
-        FieldTwo
-
-        ## FieldThree
-        FieldThree
-    """
-    with Anki(**cfg) as a:
-        notes = a.add_notes_from_file(str(file), tags, deck, update_file)
-        _added_notes_postprocessing(a, notes)
-
-
 @main.command("update-from-file")
 @click.argument("file", type=click.Path(exists=True, dir_okay=False))
 @click.option("-t", "--tags", default="", help="Specify default tags for cards.")
@@ -259,6 +194,28 @@ def update_from_file(file: Path, tags: str, deck: str, update_file: bool) -> Non
         _added_notes_postprocessing(a, notes)
 
 
+# Create an alias for backward compatibility
+@main.command("add-from-file")
+@click.argument("file", type=click.Path(exists=True, dir_okay=False))
+@click.option("-t", "--tags", default="", help="Specify default tags for new cards.")
+@click.option("-d", "--deck", help="Specify default deck for new cards.")
+@click.option(
+    "-u", "--update-file", is_flag=True, help="Update original file with note IDs."
+)
+def add_from_file(file: Path, tags: str, deck: str, update_file: bool) -> None:
+    """Add notes from Markdown file.
+
+    With the --update-file option, the original file will be updated to include
+    note IDs for any new notes added.
+
+    This command is an alias for update-from-file, which can both add new notes
+    and update existing ones.
+    """
+    with Anki(**cfg) as a:
+        notes = a.update_notes_from_file(str(file), tags, deck, update_file)
+        _added_notes_postprocessing(a, notes)
+
+
 def _added_notes_postprocessing(a: Anki, notes: list[Note]) -> None:
     """Common postprocessing after 'apy add[-from-file]' or 'apy update-from-file'."""
     n_notes = len(notes)

tests/test_cli.py

@@ -37,13 +37,27 @@ def test_cli_base_directory():
 @pytest.mark.parametrize(
     "note_files", [test_data_dir + file for file in note_files_input]
 )
-def test_cli_add_from_file(note_files):
-    """Test 'apy add-from-file' for various note file inputs."""
+def test_cli_update_from_file(note_files):
+    """Test 'apy update-from-file' for various note file inputs."""
     runner = CliRunner()
 
     with tempfile.TemporaryDirectory() as tmpdirname:
         shutil.copytree(test_collection_dir, tmpdirname, dirs_exist_ok=True)
-        result = runner.invoke(main, ["-b", tmpdirname, "add-from-file", note_files])
+        result = runner.invoke(main, ["-b", tmpdirname, "update-from-file", note_files])
+
+        assert result.exit_code == 0
+
+
+def test_cli_add_from_file_alias():
+    """Test that 'apy add-from-file' works as an alias for 'update-from-file'."""
+    runner = CliRunner()
+
+    with tempfile.TemporaryDirectory() as tmpdirname:
+        shutil.copytree(test_collection_dir, tmpdirname, dirs_exist_ok=True)
+        # Should work as an alias to update-from-file
+        result = runner.invoke(
+            main, ["-b", tmpdirname, "add-from-file", test_data_dir + "basic.md"]
+        )
 
         assert result.exit_code == 0