Skip to content


Automatic completion for optparse module.

This module provide automatic bash completion support for programs that use the optparse module. The premise is that the optparse options parser specifies enough information (and more) for us to be able to generate completion strings esily. Another advantage of this over traditional completion schemes where the completion strings are hard-coded in a separate bash source file, is that the same code that parses the options is used to generate the completions, so the completions is always up-to-date with the program itself.

In addition, we allow you specify a list of regular expressions or code that define what kinds of files should be proposed as completions to this file if needed. If you want to implement more complex behaviour, you can instead specify a function, which will be called with the current directory as an argument.

You need to activate bash completion using the shell script function that comes with optcomplete (see for more details).


  • Martin Blais (
  • Stijn De Weirdt (Ghent University)

This is a copy of (changeset 17:e0a9131a94cc) from source:

Modification by stdweird: - cleanup


Bases: Completer

Completes by listing all possible files in current directory.


Bases: object

Simple default base class implementation for a subcommand that supports command completion. This class is assuming that there might be a method addopts(self, parser) to declare options for this subcommand, and an optional completer data member to contain command-specific completion. Of course, you don't really have to use this, but if you do it is convenient to have it here.


Bases: object

Base class to derive all other completer classes from. It generates an empty completion list


Check mandatory args, then return _call


Bases: Exception

Exception to raise when call arg is missing



optparse Option class with completer attribute


Bases: Completer

Completes by listing subdirectories only.


Bases: Completer

Completes by listing all possible files in current directory. If endings are specified, then limit the files to those.


Bases: Completer

Completes a list of known hostnames


Bases: Completer

Completes by filtering using a fixed list of strings.


Bases: Completer

Generates empty completion list. For compatibility reasons.


Bases: Completer

Completes by filtering all possible files with the given list of regexps.

autocomplete(parser, arg_completer=None, opt_completer=None, subcmd_completer=None, subcommands=None)

Automatically detect if we are requested completing and if so generate completion automatically from given parser.

'parser' is the options parser to use.

'arg_completer' is a callable object that gets invoked to produce a list of completions for arguments completion (oftentimes files).

'opt_completer' is the default completer to the options that require a value.

'subcmd_completer' is the default completer for the subcommand arguments.

If 'subcommands' is specified, the script expects it to be a map of command-name to an object of any kind. We are assuming that this object is a map from command name to a pair of (options parser, completer) for the command. If the value is not such a tuple, the method 'autocomplete(completer)' is invoked on the resulting object.

This will attempt to match the first non-option argument into a subcommand name and if so will use the local parser in the corresponding map entry's value. This is used to implement completion for subcommand syntax and will not be needed in most cases.

error_override(self, msg)

Hack to keep OptionParser from writing to sys.stderr when calling self.exit from self.error

extract_word(line, point)

Return a prefix and suffix of the enclosing word. The character under the cursor is the first character of the suffix.

gen_cmdline(cmd_list, partial, shebang=True)

Create the commandline to generate simulated tabcompletion output


command to execute as list of strings


the string to autocomplete (typically, partial is an element of the cmd_list)


script has python shebang (if not, add sys.executable)



Determine the shell, update class constant SHELL and return the shell Idea is to call it just once

guess_first_nonoption(gparser, subcmds_map)

Given a global options parser, try to guess the first non-option without generating an exception. This is used for scripts that implement a subcommand syntax, so that we can generate the appropriate completions for the subcommand.

set_optionparser(option_class, optionparser_class)

Set the default Option and OptionParser class