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

Command Line Scripts

Name: tessl/pypi-argcomplete
Author: tessl

Command-line utilities for registering and activating argcomplete completion for Python scripts. These tools help set up completion for individual scripts or enable global completion support.

Entry Points

After installing argcomplete, the following command-line utilities are available:

register-python-argcomplete

Usage:

register-python-argcomplete [options] executable [executable ...]

Options:

--shell SHELL: Target shell (bash, zsh, fish, tcsh, powershell)
--complete-arguments ARGS: Custom completion arguments
--no-defaults: Disable default completion fallback
--external-argcomplete-script SCRIPT: Use external completion script

Examples:

# Basic registration (bash)
eval "$(register-python-argcomplete my-script.py)"

# Register for zsh
eval "$(register-python-argcomplete --shell zsh my-script.py)"

# Register for fish (save to file)
register-python-argcomplete --shell fish my-script.py > ~/.config/fish/completions/my-script.py.fish

# Register multiple scripts
eval "$(register-python-argcomplete my-script.py my-other-script.py)"

# Custom completion arguments
eval "$(register-python-argcomplete --complete-arguments '-o nospace' my-script.py)"

Advanced Usage:

# Use external completion script
eval "$(register-python-argcomplete --external-argcomplete-script my-completion-handler my-script.py)"

# PowerShell registration
register-python-argcomplete --shell powershell my-script.py | Out-String | Invoke-Expression

activate-global-python-argcomplete

Enable global completion for all Python scripts that support argcomplete.

Usage:

activate-global-python-argcomplete [options]

Options:

--dest DEST: Destination directory for completion files
--shell SHELL: Target shell (bash, zsh)
--user: Install for current user only
--complete-arguments ARGS: Custom completion arguments

Examples:

# Enable global completion (requires sudo for system-wide)
sudo activate-global-python-argcomplete

# Enable for current user only
activate-global-python-argcomplete --user

# Enable for zsh
activate-global-python-argcomplete --shell zsh --user

# Custom destination
activate-global-python-argcomplete --dest ~/.bash_completion.d --user

What it does:

Installs completion files to standard locations
Modifies shell configuration files to source completion
Enables completion for any script with # PYTHON_ARGCOMPLETE_OK comment

python-argcomplete-check-easy-install-script

Verify that easy_install scripts are properly set up for argcomplete.

Usage:

python-argcomplete-check-easy-install-script script-name

Purpose:

Checks if scripts installed via easy_install have proper argcomplete headers
Verifies that the # PYTHON_ARGCOMPLETE_OK marker is present
Helps diagnose completion issues with installed packages

Example:

python-argcomplete-check-easy-install-script my-installed-tool

Script Requirements

Python Script Setup

For scripts to work with argcomplete, they need:

Argcomplete marker comment (first or second line):

#!/usr/bin/env python
# PYTHON_ARGCOMPLETE_OK

import argparse
import argcomplete

Argcomplete integration:

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

argcomplete.autocomplete(parser)  # Must be before parse_args()
args = parser.parse_args()

Installation Verification

Check if completion is working:

# Test completion (should show available options)
my-script --<TAB><TAB>

# Debug completion
_ARC_DEBUG=1 my-script --<TAB>

Integration Examples

Bash Integration

Individual Script Registration

# Add to ~/.bashrc or ~/.bash_profile
eval "$(register-python-argcomplete my-project-cli)"

Global Registration

# System-wide (requires sudo)
sudo activate-global-python-argcomplete

# User-specific
activate-global-python-argcomplete --user

Zsh Integration

Individual Script

# Add to ~/.zshrc
eval "$(register-python-argcomplete --shell zsh my-script)"

Global Setup

# Enable global completion
activate-global-python-argcomplete --shell zsh --user

# Add to ~/.zshrc if not done automatically
fpath=(~/.local/share/zsh/site-functions $fpath)
autoload -U compinit && compinit

Fish Integration

# Save completion to fish config
register-python-argcomplete --shell fish my-script > ~/.config/fish/completions/my-script.fish

# Reload fish completions
fish -c "complete --erase; complete --reload"

Package Integration

For distributable packages, include completion setup in installation:

setup.py example:

from setuptools import setup

setup(
    name="my-package",
    entry_points={
        'console_scripts': [
            'my-tool=my_package.cli:main',
        ],
    },
    # Optional: Include completion setup in post-install
)

Post-install message:

print("""
To enable tab completion, run:
    eval "$(register-python-argcomplete my-tool)"

Or add this line to your ~/.bashrc
""")

Docker Integration

For containerized applications:

# Install argcomplete
RUN pip install argcomplete

# Enable completion in container
RUN activate-global-python-argcomplete --user

# Set up environment
ENV PYTHONPATH=/app
ENV _ARC_DEBUG=1  # Optional: for debugging

Troubleshooting

Common Issues

Completion not working:

# Check if script has proper marker
head -n 5 my-script.py | grep -i argcomplete

# Verify registration
type _python_argcomplete_my_script

Debug completion issues:

# Enable debug output
_ARC_DEBUG=1 my-script --<TAB>

# Check environment variables
env | grep -i comp
env | grep -i argcomplete

Shell-specific issues:

# Bash: Check completion loading
complete -p my-script

# Zsh: Check function definition
which _python_argcomplete_my_script

# Fish: List completions
complete -C my-script

Performance Issues

For slow completion:

# Profile completion time
time (my-script --<TAB> 2>/dev/null)

# Enable debug to see what's slow
_ARC_DEBUG=1 my-script --<TAB>

Permission Issues

For global installation issues:

# Use user installation instead
activate-global-python-argcomplete --user

# Check destination permissions
ls -la /etc/bash_completion.d/
ls -la ~/.bash_completion.d/

Install with Tessl CLI