optcomplete: Sample Example Output

Author:	Martin Blais <blais@furius.ca>
Date:	2004-01-26

Abstract

Some sample output and examples of what optcomplete provides.

Basic Features

For some input script with the following optparse declarations:

parser = optparse.OptionParser()

parser.add_option('-s', '--simple', action='store_true',
                  help="Simple really simple option without argument.")

parser.add_option('-o', '--output', action='store',
                  help="Option that requires an argument.")

parser.add_option('-p', '--script', action='store',
                  help="Option that takes python scripts args only.")

We modify the last option simply to add one option-specific completer (this is option, for this demo):

opt = parser.add_option('-p', '--script', action='store',
                        help="Option that takes python scripts args only.")
opt.completer = optcomplete.RegexCompleter('.*\.py')

And then, to add support for completions, we need only add a call to the autocomplete function, with optional regexps for filename completion:

# Support completion for the command-line of this script.
optcomplete.autocomplete(parser, ['.*\.tar.*'])

Here is sample output from the script.

Note

At the end of each input line I pressed <TAB> and not <ENTER>.

Files present in the test directory:

elbow:~/p/optcomplete/test$ ls -l
total 24
drwxr-xr-x    2 blais    users        4096 Jan 26 00:59 CVS
-rw-r--r--    1 blais    users           0 Jan 26 00:38 a.tar
-rw-r--r--    1 blais    users           0 Jan 26 00:38 a.tar.bz2
-rw-r--r--    1 blais    users           0 Jan 26 00:38 b.tar.gz
drwxr-xr-x    3 blais    users        4096 Jan 26 00:38 dir1
-rw-r--r--    1 blais    users        5803 Jan 26 01:03 sample-output.html
-rw-r--r--    1 blais    users        4160 Jan 26 01:04 sample-output.txt
-rw-r--r--    1 blais    users           0 Jan 26 00:38 script.sh
-rw-r--r--    1 blais    users           0 Jan 26 00:38 script1.py
-rw-r--r--    1 blais    users           0 Jan 26 00:38 script2.py

Completing without prefix outputs long and short options, and filename completion:

elbow:~/p/optcomplete/test$ optcomplete-test
--help     --script   -h         -p         a.tar      b.tar.gz
--output   --simple   -o         -s         a.tar.bz2

Completing existing short options completes simply:

elbow:~/p/optcomplete/test$ optcomplete-test -
--help    --output  --script  --simple  -h        -o        -p        -s

elbow:~/p/optcomplete/test$ optcomplete-test -s

Completing existing long options works the same:

elbow:~/p/optcomplete/test$ optcomplete-test --
--help    --output  --script  --simple

elbow:~/p/optcomplete/test$ optcomplete-test --s
elbow:~/p/optcomplete/test$ optcomplete-test --simple

Note that if an option requires an argument, other options following it are not listed as possible completions:

elbow:~/p/optcomplete/test$ optcomplete-test --output
a.tar      a.tar.bz2  b.tar.gz

elbow:~/p/optcomplete/test$ optcomplete-test --simple
--help     --script   -h         -p         a.tar      b.tar.gz
--output   --simple   -o         -s         a.tar.bz2

Option-specific completion can be easily implemented as seen above, in this example, the option --script takes files that end with .py only:

elbow:~/p/optcomplete/test$ optcomplete-test --script
script1.py  script2.py

This works anywhere on the command-line, and so on:

elbow:~/p/optcomplete/test$ optcomplete-test --simple --script script1.py
--help     --script   -h         -p         a.tar      b.tar.gz
--output   --simple   -o         -s         a.tar.bz2

Note that a partial filename will restrict the choices, as expected:

elbow:~/p/optcomplete/test$ optcomplete-test --simple --script script1.py a.
a.tar      a.tar.bz2
elbow:~/p/optcomplete/test$ optcomplete-test --simple --script script1.py a.tar

And running the program has the usual behaviour of optparse, nothing changes:

----------------------------------------------------------
opts <Values at 0x404181ac: {'simple': None, 'output': None, 'script': 'script1.py'}>
args ['a.tar']
----------------------------------------------------------

Note

It is important to note that a shell completion hook is required in order for the shell to invoke the Python script with the appropriate input to request optcomplete completion in the first place. This can be done in a bash/shell initialization file for each supported program once the shell _optcomplete function has been sourced, it could easily be setup globally:

complete -F _optcomplete optcomplete-test

Using Subcommands

You can also implement completion for subcommands, given very few restrictions. Basically, you build a map from command name to command object and give that to the autocomplete() function and it works it out for you:

elbow:~/p/optcomplete$ optcomplete-commands
--global    --version   -v          foo         help
--help      -g          bar         goo         man
--verbose   -h          completing  gore        simplest
elbow:~/p/optcomplete$ optcomplete-commands

Subcommands can have their own custom completion for their own arguments:

elbow:~/p/optcomplete$ optcomplete-commands bar
--help         -L             commands       some
--local        -h             completion
--local-other  -l             default
elbow:~/p/optcomplete$ optcomplete-commands bar

For the following interface:

elbow:~/p/optcomplete$ optcomplete-commands bar --help
usage: Bar command description, derived from foo.

options:
  -h, --help         show this help message and exit
  -l, --local        Some local option.
  -L, --local-other  Some other local option.
elbow:~/p/optcomplete$

Note above that the completions have been set to a default for all the commands, so that the words 'commands', 'some', 'completion', 'default' are produced.

You can setup command-specific completion as well:

elbow:~/p/optcomplete$ optcomplete-commands foo
--help      -h          foo_topic1
--local     -l          foo_topic2
elbow:~/p/optcomplete$ optcomplete-commands foo