Argcomplete is particularly useful if your program has lots of options or subparsers, and if your program can
dynamically suggest completions for your argument/option values (for example, if the user is browsing resources over
the network).

Shellcode (only necessary if global completion is not activated - see Global completion below), to be put in e.g. .bashrc:

eval "$(register-python-argcomplete my-awesome-script.py)"

argcomplete.autocomplete(parser)

This method is the entry point to the module. It must be called after ArgumentParser construction is complete, but
before the ArgumentParser.parse_args() method is called. The method looks for an environment variable that the
completion hook shellcode sets, and if it’s there, collects completions, prints them to the output stream (fd 8 by
default), and exits. Otherwise, it returns to the caller immediately.

Side effects

Argcomplete gets completions by running your program. It intercepts the execution flow at the moment
argcomplete.autocomplete() is called. After sending completions, it exits using exit_method (os._exit
by default). This means if your program has any side effects that happen before argcomplete is called, those
side effects will happen every time the user presses <TAB> (although anything your program prints to stdout or
stderr will be suppressed). For this reason it’s best to construct the argument parser and call
argcomplete.autocomplete() as early as possible in your execution flow.

Specifying completers

You can specify custom completion functions for your options and arguments. Two styles are supported: callable and
readline-style. Callable completers are simpler. They are called with the following keyword arguments:

prefix: The prefix text of the last word before the cursor on the command line. All returned completions should begin with this prefix.

action: The argparse.Action instance that this completer was called for.

parser: The argparse.ArgumentParser instance that the action was taken by.

parsed_args: The result of argument parsing so far (the argparse.Namespace args object normally returned by
ArgumentParser.parse_args()).

Completers should return their completions as a list of strings. An example completer for names of environment
variables might look like this:

Note that if you use the choices=<completions> option, argparse will show
all these choices in the --help output by default. To prevent this, set
metavar (like parser.add_argument("--protocol",metavar="PROTOCOL",choices=('http', 'https', 'ssh', 'rsync', 'wss'))).

The following script uses
parsed_args and Requests to query GitHub for publicly known members of an
organization and complete their names, then prints the member description:

Readline-style completers

The readline module defines a completer protocol in rlcompleter. Readline-style completers are also supported by
argcomplete, so you can use the same completer object both in an interactive readline-powered shell and on the bash
command line. For example, you can use the readline-style completer provided by IPython to get introspective
completions like you would get in the IPython shell:

Printing warnings in completers

Normal stdout/stderr output is suspended when argcomplete runs. Sometimes, though, when the user presses <TAB>, it’s
appropriate to print information about why completions generation failed. To do this, use warn:

fromargcompleteimportwarndefAwesomeWebServiceCompleter(prefix,**kwargs):iflogin_failed:warn("Please log in to Awesome Web Service to use autocompletion")returncompletions

Using a custom completion validator

By default, argcomplete validates your completions by checking if they start with the prefix given to the completer. You
can override this validation check by supplying the validator keyword to argcomplete.autocomplete():

defmy_validator(current_input,keyword_to_check_against):# Pass through ALL options even if they don't all start with 'current_input'returnTrueargcomplete.autocomplete(parser,validator=my_validator)

Global completion

In global completion mode, you don’t have to register each argcomplete-capable executable separately. Instead, bash
will look for the string PYTHON_ARGCOMPLETE_OK in the first 1024 bytes of any executable that it’s running
completion for, and if it’s found, follow the rest of the argcomplete protocol as described above.

Bash version compatibility

Global completion requires bash support for complete -D, which was introduced in bash 4.2. On OS X or older Linux
systems, you will need to update bash to use this feature. Check the version of the running copy of bash with
echo $BASH_VERSION. On OS X, install bash via Homebrew (brew install bash), add
/usr/local/bin/bash to /etc/shells, and run chsh to change your shell.

Global completion is not currently compatible with zsh.

Note

If you use setuptools/distribute scripts or entry_points directives to package your module,
argcomplete will follow the wrapper scripts to their destination and look for PYTHON_ARGCOMPLETE_OK in the
destination code.

Activating global completion

The script activate-global-python-argcomplete will try to install the file
bash_completion.d/python-argcomplete.sh (see on GitHub) into an appropriate location on your system
(/etc/bash_completion.d/ or ~/.bash_completion.d/). If it
fails, but you know the correct location of your bash completion scripts directory, you can specify it with --dest:

activate-global-python-argcomplete --dest=/path/to/bash_completion.d

Otherwise, you can redirect its shellcode output into a file:

activate-global-python-argcomplete --dest=- > file

The file’s contents should then be sourced in e.g. ~/.bashrc.

Debugging

Set the _ARC_DEBUG variable in your shell to enable verbose debug output every time argcomplete runs. Alternatively,
you can bypass the bash completion shellcode altogether, and interact with the Python code directly with something like
this: