or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

completers.mdcompletion-engine.mdindex.mdscripts.mdshell-integration.mdutilities.md
tile.json

tessl/pypi-argcomplete

Bash tab completion for argparse

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
pypipkg:pypi/argcomplete@3.6.x

To install, run

npx @tessl/cli install tessl/pypi-argcomplete@3.6.0

index.mddocs/

Argcomplete

Argcomplete provides powerful bash/zsh tab completion for Python applications using argparse. It enables developers to add interactive command-line completion capabilities to their Python scripts and applications, supporting both static and dynamic completion scenarios with custom completers, choice validation, environment variable integration, and real-time API-based completions.

Package Information

  • Package Name: argcomplete
  • Language: Python
  • Installation: pip install argcomplete

Core Imports

import argcomplete

For most use cases:

from argcomplete import autocomplete

For specific completers:

from argcomplete import ChoicesCompleter, FilesCompleter, DirectoriesCompleter

Basic Usage

#!/usr/bin/env python
# PYTHON_ARGCOMPLETE_OK

import argparse
import argcomplete

# Create argument parser
parser = argparse.ArgumentParser(description='My CLI tool')
parser.add_argument('--name', help='Name to greet')
parser.add_argument('--config', type=argparse.FileType('r'),
                   help='Configuration file')

# Enable argcomplete
argcomplete.autocomplete(parser)

# Parse arguments normally
args = parser.parse_args()
print(f"Hello, {args.name}!")

Then register the script for completion:

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

Architecture

Argcomplete uses a patching mechanism to intercept argparse operations during completion:

  • CompletionFinder: Core engine that patches argparse parsers to collect completion candidates
  • Completers: Pluggable completion strategies (files, choices, directories, environment variables)
  • Shell Integration: Generated shell code that interfaces with the completion system
  • Lexers: Command line parsing utilities that respect shell quoting and word boundaries

The system activates only when shell completion environment variables are present, allowing scripts to function normally during regular execution while providing rich completion during tab completion.

Capabilities

Core Completion Engine

The main completion system that provides the primary interface for enabling tab completion in Python scripts using argparse.

autocomplete: CompletionFinder  # Pre-instantiated completion finder

# Usage: autocomplete(parser, **kwargs) calls CompletionFinder.__call__()
class CompletionFinder:
    def __init__(
        self,
        argument_parser=None,
        always_complete_options=True,
        exclude=None,
        validator=None,
        print_suppressed=False,
        default_completer=FilesCompleter(),
        append_space=None
    )
    
    def __call__(
        self,
        argument_parser: argparse.ArgumentParser,
        always_complete_options: Union[bool, str] = True,
        exit_method: Callable = os._exit,
        output_stream: Optional[TextIO] = None,
        exclude: Optional[Sequence[str]] = None,
        validator: Optional[Callable] = None,
        print_suppressed: bool = False,
        append_space: Optional[bool] = None,
        default_completer: BaseCompleter = FilesCompleter()
    ) -> None

Core Completion Engine

Completers

Built-in completer classes that provide different completion strategies for various argument types, including file paths, directories, predefined choices, and environment variables.

class BaseCompleter:
    def __call__(
        self, 
        *, 
        prefix: str, 
        action: argparse.Action, 
        parser: argparse.ArgumentParser, 
        parsed_args: argparse.Namespace
    ) -> None
class ChoicesCompleter(BaseCompleter):
    def __init__(self, choices)
    def __call__(self, **kwargs)

class FilesCompleter(BaseCompleter):
    def __init__(self, allowednames=(), directories=True)
    def __call__(self, prefix, **kwargs)

class DirectoriesCompleter(BaseCompleter):
    def __init__(self)

class SuppressCompleter(BaseCompleter):
    def __init__(self)
    def suppress(self) -> bool
EnvironCompleter: ChoicesCompleter  # Pre-configured with os.environ

Completers

Shell Integration

Functions for generating shell-specific completion code that can be sourced or registered with the shell's completion system.

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

Shell Integration

Utility Functions

Support functions for debugging, output control, and command line parsing during completion operations.

def debug(*args) -> None
def warn(*args) -> None
def split_line(line: str, point: Optional[int] = None) -> Tuple[str, str, str, List[str], Optional[int]]
safe_actions: Set[Type[argparse.Action]]

Utilities

Command Line Scripts

Command-line utilities for registering and activating argcomplete completion for Python scripts globally or individually.

Entry points available after installation:

  • register-python-argcomplete - Register individual scripts
  • activate-global-python-argcomplete - Enable global completion
  • python-argcomplete-check-easy-install-script - Validate easy install scripts

Command Line Scripts

Types

class ArgcompleteException(Exception):
    """Exception raised when the shell argument completion process fails."""

class ExclusiveCompletionFinder(CompletionFinder):
    """Variant of CompletionFinder that provides exclusive completion behavior."""