bash-completion.rst

Overview

This documentation file provides instructions on how to enable and use **bash completion** for the `pytest` command-line tool when running in a bash shell. Bash completion enhances the user experience by providing **command and argument auto-completion** functionality, making it faster and easier to use `pytest` from the terminal.

The file primarily explains how to install and activate the `argcomplete` Python package, which is the underlying library enabling bash completion support for Python CLI applications like `pytest`. It details different methods of activation, ranging from global system-wide setup to one-time session activation.

This file is a user-facing guide rather than a code implementation file. It contains no functions or classes but focuses on setup instructions with example shell commands.

Detailed Content Explanation

Purpose

To instruct users on setting up bash shell auto-completion support for pytest.
To guide through installation and activation procedures of the argcomplete tool that enables this feature.

Key Instructions

Installing argcomplete
Users must install argcomplete with pip:
```
sudo pip install 'argcomplete>=0.5.7'
```
Global Activation
To enable bash completion for all Python applications that support argcomplete globally:
```
sudo activate-global-python-argcomplete
```
This modifies the system bash completion scripts so that any argcomplete-enabled Python CLI tool will have completion enabled automatically.
Permanent Activation for pytest Only
Instead of global activation, users can register bash completion for pytest specifically by appending the registration command to their .bashrc file:
```
register-python-argcomplete pytest >> ~/.bashrc
```
This ensures bash completion is enabled for pytest every time a new shell is started.
One-Time Activation
For a temporary session-only activation (no persistent changes), users can run:
```
eval "$(register-python-argcomplete pytest)"
```
This activates completion only for the current shell session.

Usage Examples

To illustrate, here are usage examples corresponding to each activation method:

Install argcomplete
```
sudo pip install 'argcomplete>=0.5.7'
```

Activate globally

sudo activate-global-python-argcomplete

Permanent activation for pytest

register-python-argcomplete pytest >> ~/.bashrc
source ~/.bashrc

One-time activation

eval "$(register-python-argcomplete pytest)"

Once activated, typing `pytest` followed by pressing the `Tab` key twice in bash will show possible options or subcommands for `pytest`, speeding up command entry.

Implementation Details

This file is a reStructuredText (RST) document used for project documentation.
It does not contain executable code but provides shell commands to set up completion.
The instructions rely on the argcomplete Python package, which hooks into bash’s programmable completion system.
The file references the official argcomplete documentation (https://kislyuk.github.io/argcomplete/) for further details.
Activation commands use register-python-argcomplete and activate-global-python-argcomplete scripts installed by argcomplete.

Interaction with the System and Other Components

This document interacts indirectly with the pytest CLI tool by enabling shell integration for it.
The bash shell must support programmable completion (bash-completion package usually installed).
argcomplete acts as a middleware between the shell and the pytest CLI, providing completion suggestions.
The activation commands modify shell initialization files (~/.bashrc) or system completion scripts to hook pytest completion.
This setup enhances the user interface layer of the overall system by improving command-line usability.

Visual Diagram

The following **flowchart** illustrates the workflow of enabling bash completion for `pytest` via `argcomplete`:

flowchart TD
    A[User wants bash completion for pytest] --> B[Install argcomplete package]
    B --> C{Choose activation method}
    C -->|Global activation| D[Run sudo activate-global-python-argcomplete]
    C -->|Permanent pytest only| E[Run register-python-argcomplete pytest >> ~/.bashrc]
    C -->|One-time activation| F[Run eval "$(register-python-argcomplete pytest)"]
    D --> G[Bash completion enabled globally]
    E --> H[Bash completion enabled for pytest in new shells]
    F --> I[Bash completion enabled for pytest in current session]
    G --> J[User types pytest + Tab in bash]
    H --> J
    I --> J
    J --> K[Shell invokes argcomplete script]
    K --> L[pytest CLI completion options displayed]

Summary

This file is a concise guide for users to enable bash command-line completion for the `pytest` testing tool. It covers installation, various activation methods, and links to the underlying `argcomplete` technology. By following these instructions, users can enhance their terminal experience, reducing typing effort and errors when using `pytest`.