Completions

The completion engine provided by the base python cmd module is very confusing and not easily approachable. There are a few helper methods provided (and used by default) to generate the completions for a command in the various stages of the command composition.

Syntax Note

Throughout this page, there will be sections that show the state of a command being composed and completions being requested. The syntax used will include a character ▯ in the line where the completion is requested (this is normally done using <Tab>). So in:

$ complete this▯

The completion will be for the this argument in the composition (based on the complete command).

Completion Function

If you want to write your own completion function, you need to have it meet the argument map compatible with the underlying readline interface used by the include cmd module.

The basic signature of the function used to generate completions looks like:

def completion_func(current_argument, command_text, *_args)

• The *_args is just a collection of the other arguments passed in, they are begidx and endidx .
• The current_argument is the active “word” in the overall command composition.
• The command_text is the full argument string for the command being composed.

For example in the case of

$ set name Mar▯

The values would be Mar for current_argument and set name Mar for command_text.

Generation Helpers

You can also provide either a list or dict to be converted into a completion function. The list just dictates possible values that can be suggested regardless of the state of the other arguments (the order is arbitrary). So with a completion set of foo, bar, baz the completions would be:

$ complete foo ba▯
bar baz
$ complete ba▯
bar baz
$ complete foo bar ba▯
bar baz

If you provide a dict, the keys make up the first layer of suggestions for the command. Then the second layer is made up of the value of the key corresponding to the first argument, if this value is a dict, it is used the same way, if it is a list it behaves the same was as above. If the completion set is:

{ "language": ["spanish", "french", "english"],
  "os": { "bsd": ["freebsd", "openbsd"],
          "linux": ["debian", "arch", "gentoo"] },
  "wm": ["xmonad", "openbox", "gnome"] }

The completions would look like:

$ complete ▯
language os wm
$ complete lang▯
language
$ complete language ▯
spanish french english
$ complete os ▯
bsd linux
$ complete os linux ▯
debian arch gentoo
$ compelte os bsd ▯
freebsd openbsd