tessl/pypi-argcomplete

Bash tab completion for argparse

—

Pending

Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Overview

Eval results

Files

Shell Integration

Name: tessl/pypi-argcomplete
Author: tessl

Functions for generating shell-specific completion code that integrates argcomplete with various shell environments. The shell integration system generates the necessary shell code to bridge between the shell's completion system and Python-based completion logic.

Capabilities

Shell Code Generation

Generate shell-specific completion code for different shell environments.

def shellcode(
    executables: List[str], 
    use_defaults: bool = True, 
    shell: str = "bash", 
    complete_arguments: Optional[List[str]] = None, 
    argcomplete_script: Optional[str] = None
) -> str

Parameters:

executables: List of executable names to enable completion for
use_defaults: Whether to fallback to readline's default completion (bash only)
shell: Target shell ("bash", "zsh", "fish", "tcsh", "powershell")
complete_arguments: Custom arguments for the complete command (bash only)
argcomplete_script: Alternative script to call for completion

Returns:

String containing shell code ready to be sourced or evaluated

Usage:

from argcomplete import shellcode

# Generate bash completion code
bash_code = shellcode(['my-script', 'my-other-script'], shell='bash')
print(bash_code)

# Generate zsh completion code
zsh_code = shellcode(['my-script'], shell='zsh')

# Generate fish completion code
fish_code = shellcode(['my-script'], shell='fish')

# Disable default completions
code = shellcode(['my-script'], use_defaults=False)

# Custom complete arguments
code = shellcode(['my-script'], complete_arguments=['-o', 'nospace'])

Shell-Specific Features

Bash Integration

Generates bash completion code that integrates with the bash completion system:

# Example generated bash code
_python_argcomplete_my_script() {
    local IFS=$'\013'
    COMPREPLY=($(IFS="$IFS" \
        COMP_LINE="$COMP_LINE" \
        COMP_POINT="$COMP_POINT" \
        _ARGCOMPLETE=1 \
        _ARGCOMPLETE_SHELL="bash" \
        __python_argcomplete_run my-script))
}
complete -o nospace -o default -o bashdefault -F _python_argcomplete_my_script my-script

Features:

Supports COMP_WORDBREAKS customization
Handles space suppression for continuation characters
Integrates with bash-completion system

Zsh Integration

Generates zsh completion code using the _describe function:

# Example generated zsh code
_python_argcomplete_my_script() {
    local completions
    completions=($(IFS="$IFS" \
        COMP_LINE="$BUFFER" \
        COMP_POINT="$CURSOR" \
        _ARGCOMPLETE=1 \
        _ARGCOMPLETE_SHELL="zsh" \
        __python_argcomplete_run my-script))
    _describe "my-script" completions
}
compdef _python_argcomplete_my_script my-script

Features:

Uses zsh's _describe for rich completions with descriptions
Handles cursor position mapping
Supports zsh-specific completion features

Fish Integration

Generates fish shell completion code:

# Example generated fish code
function __fish_my_script_complete
    set -x _ARGCOMPLETE 1
    set -x _ARGCOMPLETE_SHELL fish
    set -x COMP_LINE (commandline -p)
    set -x COMP_POINT (string length (commandline -cp))
    my-script 8>&1 9>&2 1>/dev/null 2>&1
end
complete --command my-script -f -a '(__fish_my_script_complete)'

Features:

Uses fish's command line utilities
Supports tab-separated descriptions
Integrates with fish completion system

PowerShell Integration

Generates PowerShell completion code using Register-ArgumentCompleter:

# Example generated PowerShell code
Register-ArgumentCompleter -Native -CommandName my-script -ScriptBlock {
    param($commandName, $wordToComplete, $cursorPosition)
    $env:_ARGCOMPLETE = 1
    $env:_ARGCOMPLETE_SHELL = "powershell"
    $env:COMP_LINE = $wordToComplete
    $env:COMP_POINT = $cursorPosition
    my-script 2>&1 | Out-Null | ForEach-Object {
        [System.Management.Automation.CompletionResult]::new($_, $_, "ParameterValue", $_)
    }
}

Tcsh Integration

Generates tcsh completion code:

# Example generated tcsh code
complete "my-script" 'p@*@`python-argcomplete-tcsh "my-script"`@' ;

Advanced Usage

Multiple Executables

Generate completion for multiple related scripts:

code = shellcode([
    'my-tool',
    'my-tool-admin', 
    'my-tool-dev'
], shell='bash')

Custom Completion Script

Use a different script for completion than the executable being completed:

# All executables use the same completion script
code = shellcode(
    ['my-tool', 'my-tool-legacy'],
    argcomplete_script='my-tool-completion'
)

Integration Examples

Register with Shell

# Bash
eval "$(python -c "from argcomplete import shellcode; print(shellcode(['my-script']))")"

# Or save to file
python -c "from argcomplete import shellcode; print(shellcode(['my-script']))" > my-script-completion.bash
source my-script-completion.bash

Zsh Setup

# Add to .zshrc
eval "$(python -c "from argcomplete import shellcode; print(shellcode(['my-script'], shell='zsh'))")"

Fish Setup

# Save to completion file
python -c "from argcomplete import shellcode; print(shellcode(['my-script'], shell='fish'))" > ~/.config/fish/completions/my-script.fish

Environment Variables

The shell integration relies on specific environment variables during completion:

Core Variables

_ARGCOMPLETE: Set to indicate completion mode
_ARGCOMPLETE_SHELL: Target shell type
COMP_LINE: Full command line being completed
COMP_POINT: Cursor position in the command line

Control Variables

_ARGCOMPLETE_SUPPRESS_SPACE: Control space appending
_ARGCOMPLETE_IFS: Internal field separator for completion output
_ARGCOMPLETE_DFS: Description field separator
_ARGCOMPLETE_COMP_WORDBREAKS: Word break characters
_ARC_DEBUG: Enable debug output

File Output Variables

_ARGCOMPLETE_STDOUT_FILENAME: Redirect completion output to file
ARGCOMPLETE_USE_TEMPFILES: Use temporary files for IPC

Debugging Shell Integration

Enable debug output to troubleshoot completion issues:

export _ARC_DEBUG=1
my-script <TAB>  # Debug output will show in terminal

The debug output includes:

Parsed command line components
Active parsers and actions
Generated completions
Shell-specific processing steps

Install with Tessl CLI

npx tessl i tessl/pypi-argcomplete

docs

tessl/pypi-argcomplete