Metadata-Version: 2.4
Name: conda-completion
Version: 0.1.0
Summary: Fast shell tab completion for conda and all its plugins
Project-URL: repository, https://github.com/conda-incubator/conda-completion
Author-email: Jannis Leidel <jannis@leidel.info>
License: BSD-3-Clause
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Requires-Dist: conda-completer
Requires-Dist: conda>=25.1
Requires-Dist: platformdirs>=4.0
Requires-Dist: tomli-w>=1.0
Requires-Dist: tomli>=2.0; python_version < '3.11'
Description-Content-Type: text/markdown

# conda-completion

Fast shell tab completion for conda and all its plugins.

A hybrid Python/Rust conda plugin that introspects conda's argparse tree
(including all plugin subcommands) and provides instant TAB completions
via a tiny Rust binary.

## Features

- Completes all conda commands, flags, and plugin subcommands
- Contextual completions: environment names, task names, channels from
  project files (`conda.toml`, `pixi.toml`, `pyproject.toml`, `environment.yml`,
  `anaconda-project.yml`, `conda-project.yml`, lockfiles)
- Descriptions shown alongside candidates (zsh, fish, PowerShell)
- Sub-5ms response time (stat-cached context, no Python on the hot path)
- Shell support: bash, zsh, PowerShell (fully tested), fish (community-tested)
- Auto-regenerates the completion manifest when plugins are installed or removed

## Status

This project is in early development. It is not yet published to conda-forge.

## Quick start (development)

```bash
# Clone and set up
git clone https://github.com/conda-incubator/conda-completion
cd conda-completion
pixi install
pixi run build

# Generate the completion manifest
conda completion generate

# Install the shell hook (auto-detects your shell)
conda completion install

# Or target a specific shell
conda completion install bash

# Or use eval directly in your RC file
eval "$(conda completion init bash)"
```

## How it works

conda-completion splits the work into two phases:

**Phase 1: Generation (Python, runs once).** `conda completion generate`
calls conda's `generate_parser()`, which loads all registered plugin
subcommands. The argparse tree is walked recursively to extract commands,
flags, positional arguments, and help text. The output is a
`completion.toml` manifest stored in the platform cache directory.

**Phase 2: Completion (Rust, runs on every TAB).** When you press TAB,
your shell calls `_conda_completer`, a small Rust binary (~850 KB). It
reads the TOML manifest for static command/flag completions, then walks
project files in your working directory for dynamic completions
(environment names, task names, channels). No Python runs on the hot
path.

A stat-based file cache tracks `(mtime, size)` for every source file.
If nothing changed since the last TAB press, the binary skips all
parsing and serves cached results in under 5 ms.

### What files are read

**Project files** (walks upward from cwd, first match wins):

| File | What it provides |
| --- | --- |
| `conda.toml` / `pixi.toml` / `pyproject.toml` | Environment names, task names, feature names, channels |
| `anaconda-project.yml` | Environment names, command names |
| `conda-project.yml` | Environment names, command names |
| `environment.yml` | Environment name, channels |
| `conda.lock` / `pixi.lock` | Locked environment names and channels |
| `conda-lock.yml` | Channel names |

**Global state** (always read):

| File | What it provides |
| --- | --- |
| `~/.conda/environments.txt` | All registered environment names |
| `~/.condarc` | Configured channel names |
| `~/.conda/global/global.toml` | Globally installed tool names |

### CLI commands

| Command | Description |
| --- | --- |
| `conda completion generate` | Introspect conda's parser, write `completion.toml` |
| `conda completion install [shell]` | Generate + install shell RC hook (auto-detects shell) |
| `conda completion uninstall [shell]` | Remove the RC hook |
| `conda completion init <shell>` | Print the shell script to stdout |

`install` and `uninstall` support `--dry-run` to preview changes and
`--yes` to skip confirmation.

## Development

```bash
pixi install
pixi run build       # build Rust binary (release)
pixi run build-debug # build Rust binary (debug)
pixi run test        # run Python + Rust integration tests
pixi run check       # lint + format + typecheck + clippy
```

## License

BSD-3-Clause
