argcomplete

Git Bash does not support argcomplete out of the box due to file descriptor inheritance limitations on Windows. To enable support, you must opt into using temporary files for Inter-Process Communication (IPC) by setting the ARGCOMPLETE_USE_TEMPFILES environment variable to 1.

You can do this by adding the following to your ~/.bashrc file:

export ARGCOMPLETE_USE_TEMPFILES=1

For full, native support, it is recommended to use Bash via the Windows Subsystem for Linux (WSL).

If you do not want to use global completion, or if you are shipping a completion module that depends on argcomplete, you must register your script explicitly.

Use the following command to register a script (e.g., my-python-app):

eval "$(register-python-argcomplete my-python-app)"

Important Constraints:

• The script name passed to register-python-argcomplete is passed directly to the shell's complete command.
• Completion will only work if the script is invoked exactly as it was registered. For example, if registered as my-python-app, it will work when called as my-python-app, but not when called as ./my-python-app or /path/to/my-python-app unless those specific paths are registered.

To install argcomplete and enable global completion support, run the following commands:

1. Install the package via pip:

   pip install argcomplete

2. Activate global completion:

   activate-global-python-argcomplete

3. Refresh your shell environment (e.g., start a new shell session).

To activate completions for PowerShell, you can either source the output directly in your current session or create a module file for permanent use.

Option 1: Direct sourcing (Session-based)

register-python-argcomplete --shell powershell my-awesome-script | Out-String | Invoke-Expression

Option 2: Create a module file (Permanent)

1. Generate the module file:

register-python-argcomplete --shell powershell my-awesome-script > ~/my-awesome-script.psm1

2. Add the following line to your $PROFILE to load it automatically:

Import-Module "~/my-awesome-script.psm1"

To edit your profile, you can run notepad $PROFILE in PowerShell.

To enable tab completion for your Python application, you must perform three steps:

1. Add the marker: Place the # PYTHON_ARGCOMPLETE_OK comment at the very beginning of your entry point file. If using pyproject.toml [project.scripts], this marker must be in the file containing the entry point.
2. Call autocomplete: Call argcomplete.autocomplete(parser) after your ArgumentParser is fully constructed, but before calling parser.parse_args().
3. Register the application: Run the following command in your shell to register your specific application (ensure you use quotes):

   eval "$(register-python-argcomplete my-python-app)"

```python
#!/usr/bin/env python
# PYTHON_ARGCOMPLETE_OK
import argcomplete, argparse

parser = argparse.ArgumentParser()
# ... define arguments ...

argcomplete.autocomplete(parser)
args = parser.parse_args()

The CompletionFinder class is the core engine for generating tab completions. While you should typically use the convenience function argcomplete.autocomplete(), you can inherit from CompletionFinder to override specific stages of the completion lifecycle.

Key stages you can override include:

• collect_completions: Visiting active parsers and actions to collect option strings and execute completers.
• filter_completions: De-duplicating or excluding specific completions based on the exclude container.
• quote_completions: Handling shell-specific escaping and quoting for the resulting completion strings.

If you do not subclass it, use argcomplete.autocomplete(), which has the same signature as the CompletionFinder.__call__ method.

Use the register-python-argcomplete script to generate the shell code required to enable tab completion for a Python script that uses argcomplete. To activate completion in your current session, you must eval the output of the script.

Bash/Zsh

Execute the following command to register your script:

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

Tcsh

eval `register-python-argcomplete --shell tcsh my-favorite-script.py`

Fish

Redirect the output to a fish configuration file:

register-python-argcomplete --shell fish my-favourite-script.py > ~/.config/fish/my-favourite-script.py.fish

To troubleshoot why completion is failing, you can enable verbose debug output by setting the _ARC_DEBUG environment variable in your shell.

Warning: Enabling debug mode will disrupt the command line composition state of your terminal, but it will allow you to see the internal state of the completer when it encounters problems.

If global completion is not working for your script, Bash may have already registered a default (and incorrect) completion function.

You can check if a script has a registered completion function using:

complete | grep my-python-app

If you see an entry like complete -F _minimal my-python-app, you can fix it by either restarting your shell or by manually unregistering the existing completion with:

complete -r my-python-app