diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index ce7daeb..8e56cdf 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -7,6 +7,17 @@ on: workflow_dispatch: jobs: + shell-completion: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v5 + - uses: actions/setup-python@v6 + with: + python-version: '3.12' + - run: sudo apt-get update && sudo apt-get install -y fish zsh + - run: python -m pip install -e ".[test]" + - run: python -m pytest tests/test_completion.py tests/test_shell_activation.py + test: strategy: fail-fast: false diff --git a/CHANGELOG.md b/CHANGELOG.md index 5540e38..ca71ad7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,25 @@ # Changelog +## 1.2.0 - 2026-10-19 + +Stable release of the declarative environment workflow and live shell completion. + +- Enable context-aware Tab completion alongside shell activation for Bash, Zsh, + Fish, and PowerShell. Complete commands and aliases, options and fixed values, + environment IDs/names, Python IDs/aliases, source filters, repositories, local + package names, directories, and TOML paths using read-only local resources. +- Keep Zsh completion compact: show matching values without repeated group + headings or descriptions, and suggest options only after `-` is typed. +- Fix shell dispatch for the `remote` command, so it is not treated as an + environment name by the shell activation wrapper. +- Explain missing shell integration when an environment name or ID reaches the + executable, including a command to enable activation without restarting. +- Print commands to enable activation in the current terminal after installation, + rather than requiring users to discover that their updated shell profile must + be loaded first. +- Exercise create, activate, create-while-active, ID switching, and project-local + activation in persistent bash and zsh subprocesses using the real launcher. + ## 1.2.0b1 - 2026-09-28 Feature-complete beta for the declarative environment workflow. diff --git a/README.md b/README.md index 7456cde..905bdb4 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # pload -![pload welcome screen on macOS](docs/images/pload-welcome-macos.png) +![pload welcome screen on macOS](https://raw.githubusercontent.com/HugoPhi/pload/main/docs/images/pload-welcome-macos.png) `pload` is a relocatable Python runtime and virtual-environment manager for Bash, Zsh, Fish, and PowerShell. Its private runtime, downloaded Python @@ -80,7 +80,7 @@ profile when `--shell` is supplied or already configured. ## Reproduce and share environments -The `1.2` preview uses one clean, user-authored `pload.toml` as portable intent. +The declarative workflow uses one clean, user-authored `pload.toml` as portable intent. pload manages `.pload_lock.toml` (exact versions and artifacts) and `.pload_plan.toml` (the selected acquisition route for every package): @@ -144,28 +144,19 @@ For an installation managed by `pload-install`, upgrade the private runtime in place. Your configured directories, registry, downloaded Python runtimes, and virtual environments are kept: -```console -pload-install --yes --package-spec "pload==1.0.0" -``` - -To opt into the declarative-environment pre-release for testing: - -```console -pload-install --yes --package-spec "pload==1.2.0b1" -``` - -To always follow the newest published release instead of pinning a version, -omit the version constraint: - ```console pload-install --yes --package-spec pload ``` +The unpinned `pload` package spec follows the newest stable release on the +selected package index. Supplying it explicitly also replaces a version pin +saved by an earlier installer run. + If your selected mirror has not synchronized the release yet, choose the official index for this run (or replace it with another configured index): ```console -pload-install --yes --package-spec "pload==1.0.0" --pip-index https://pypi.org/simple +pload-install --yes --package-spec pload --pip-index https://pypi.org/simple ``` For pipx installations use pipx's own upgrade command: @@ -174,6 +165,13 @@ For pipx installations use pipx's own upgrade command: pipx upgrade pload ``` +If you installed with `python -m pip install --user pload` on a system that +allows user-site installs, upgrade using that same interpreter: + +```console +python -m pip install --user --upgrade pload +``` + For a dedicated bootstrap virtual environment, run pip through that same interpreter: @@ -247,7 +245,12 @@ environments. Configuration is stored in `PLOAD_HOME/config.json`. ## Shell activation -The installer can update a shell profile. To configure it manually: +The installer updates the selected shell profile for future terminals. In the +terminal where you just installed pload, run the matching command below once; +the installer also prints it. Environment activation is then available +immediately, including for environments created afterward. + +To configure activation manually: ```bash # Bash @@ -269,6 +272,40 @@ Invoke-Expression (& pload shell-init powershell | Out-String) Then `pload v1`, `pload data`, and `pload .` can activate environments in the current shell. +The same shell integration enables Tab completion for Bash, Zsh, Fish, and +PowerShell. After upgrading, evaluate the matching command above once to refresh +both activation and completion in the current terminal. + +Zsh completion shows only matching values in the shell's normal compact list. +At `pload `, it suggests primary commands and available environment IDs; +type part of an alias or environment name to find it. Options appear when you +type `-`, such as `pload new -`. No separate completion tool is required. + +![Compact Zsh Tab completion on macOS](https://raw.githubusercontent.com/HugoPhi/pload/main/docs/images/pload-completion-macos.png) + +| Type, then press Tab | Suggested values | +| --- | --- | +| `pload v` | Existing environment IDs, such as `v1` and `v3` | +| `pload data` | Matching environment names | +| `pload py ` | `install`, `list`, `path`; typing `l` or `p` also finds aliases | +| `pload new -v py` | Python IDs, such as `py1` and `py2` | +| `pload new -v uv-` | Installed Python aliases, such as `uv-v3.12.8` | +| `pload py path ` | Python IDs, aliases, and installed versions | +| `pload new --` | Creation options, including `--name` and `--message` | +| `pload py ls -f uv,c` | Comma-separated source types, such as `uv,conda` | +| `pload rm ` or `pload describe ` | Existing environment IDs and names | +| `pload cfg set ` | Setting names, followed by supported setting values | +| `pload remote add numpy --remote ` | Configured repository names | +| `pload apply ` or `pload init -P ` | TOML files or directories, respectively | + +Environment candidates update on each Tab, so creating or removing an environment +does not require restarting the shell. Python ID and alias candidates use the +local interpreter registry; run `pload py ls` to discover or refresh interpreters +first. Completion only reads local files: it does not download packages, probe +interpreters, contact SSH repositories, or add environments to the registry. +Package-name suggestions come from local cached wheels and, for remote backup, +the selected environment's installed metadata; they are not a full PyPI search. + ## Discover and install Python `pload python list` scans usable interpreters from the operating system, PATH, @@ -292,7 +329,7 @@ py2 conda-v3.11.9 3.11.9 conda ~/miniforge3/envs/data/bin/python The ID and alias are separate columns in the real output: -![Python runtime discovery on macOS](docs/images/pload-python-list-macos.png) +![Python runtime discovery on macOS](https://raw.githubusercontent.com/HugoPhi/pload/main/docs/images/pload-python-list-macos.png) Use any of these forms when selecting an interpreter: @@ -357,7 +394,7 @@ Every managed environment receives an ID such as `v1`, `v2`, or `v3`, plus a description and creation timestamp. Deleted IDs are reused from the first available number. `pload list` displays environments newest-first: -![Environment list on macOS](docs/images/pload-list-macos.png) +![Environment list on macOS](https://raw.githubusercontent.com/HugoPhi/pload/main/docs/images/pload-list-macos.png) The table includes ID, name, Python version, description, and full path. A spinner is shown in interactive terminals; redirected and CI output uses stable @@ -387,7 +424,7 @@ pload-install -h The root help keeps global storage options together, while command-specific help shows only that command's arguments: -![Root help on macOS](docs/images/pload-help-macos.png) +![Root help on macOS](https://raw.githubusercontent.com/HugoPhi/pload/main/docs/images/pload-help-macos.png) Detailed help adds examples, expected output, disk effects, and failure behavior: diff --git a/docs/declarative-environments.md b/docs/declarative-environments.md index 30ecd4d..b35aaa1 100644 --- a/docs/declarative-environments.md +++ b/docs/declarative-environments.md @@ -1,6 +1,6 @@ # Declarative environments -The `1.2` preview treats reproduction as resource scheduling, not as a sequence +The declarative workflow treats reproduction as resource scheduling, not as a sequence of commands the user must design. You carry one small `pload.toml`; pload resolves exact versions, inventories available resources, saves an auditable route for every package, and executes exactly those routes. diff --git a/docs/images/pload-completion-macos.png b/docs/images/pload-completion-macos.png new file mode 100644 index 0000000..a2581f7 Binary files /dev/null and b/docs/images/pload-completion-macos.png differ diff --git a/docs/images/pload-help-macos.png b/docs/images/pload-help-macos.png index f824223..7b626cf 100644 Binary files a/docs/images/pload-help-macos.png and b/docs/images/pload-help-macos.png differ diff --git a/docs/images/pload-list-macos.png b/docs/images/pload-list-macos.png index db4448c..0156591 100644 Binary files a/docs/images/pload-list-macos.png and b/docs/images/pload-list-macos.png differ diff --git a/docs/images/pload-python-list-macos.png b/docs/images/pload-python-list-macos.png index 30c25b7..56fbb15 100644 Binary files a/docs/images/pload-python-list-macos.png and b/docs/images/pload-python-list-macos.png differ diff --git a/docs/images/pload-welcome-macos.png b/docs/images/pload-welcome-macos.png index 6a99339..af059e5 100644 Binary files a/docs/images/pload-welcome-macos.png and b/docs/images/pload-welcome-macos.png differ diff --git a/pyproject.toml b/pyproject.toml index 3934127..df69549 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta" [project] name = "pload" -version = "1.2.0b1" +version = "1.2.0" description = "A small, relocatable Python virtual environment manager" readme = "README.md" requires-python = ">=3.8" @@ -12,7 +12,7 @@ license = { file = "LICENSE" } authors = [{ name = "Yunming Hu", email = "hugonelsonm3@gmail.com" }] keywords = ["python", "venv", "virtual-environment", "pyenv"] classifiers = [ - "Development Status :: 3 - Alpha", + "Development Status :: 5 - Production/Stable", "Environment :: Console", "Operating System :: MacOS", "Operating System :: Microsoft :: Windows", diff --git a/src/pload/__init__.py b/src/pload/__init__.py index 4834673..c68196d 100644 --- a/src/pload/__init__.py +++ b/src/pload/__init__.py @@ -1 +1 @@ -__version__ = "1.2.0b1" +__version__ = "1.2.0" diff --git a/src/pload/cli.py b/src/pload/cli.py index 58565f7..2c67ec7 100644 --- a/src/pload/cli.py +++ b/src/pload/cli.py @@ -1,5 +1,6 @@ import argparse import json +import os import re import sys from pathlib import Path @@ -883,10 +884,16 @@ def render_landing(): def shell_script(shell): + from pload.completion import shell_completion + + return _activation_script(shell) + "\n" + shell_completion(shell) + + +def _activation_script(shell): if shell in {"bash", "zsh"}: return r'''pload() { case "${1:-}" in - ""|new|init|i|rm|remove|del|delete|list|ls|path|p|shell-init|shell|python|py|config|cfg|describe|lock|plan|apply|repo|-*) + ""|new|init|i|rm|remove|del|delete|list|ls|path|p|shell-init|shell|python|py|config|cfg|describe|lock|plan|apply|repo|remote|-*) command pload "$@" ;; *) @@ -899,7 +906,7 @@ def shell_script(shell): if shell == "fish": return r'''function pload switch "$argv[1]" - case '' new init i rm remove del delete list ls path p shell-init shell python py config cfg describe lock plan apply repo '-*' + case '' new init i rm remove del delete list ls path p shell-init shell python py config cfg describe lock plan apply repo remote '-*' command pload $argv case '*' set -l name . @@ -913,8 +920,8 @@ def shell_script(shell): end''' return r'''function pload { param([Parameter(ValueFromRemainingArguments = $true)][string[]]$PloadArgs) - $commands = @('new', 'init', 'i', 'rm', 'remove', 'del', 'delete', 'list', 'ls', 'path', 'p', 'shell-init', 'shell', 'python', 'py', 'config', 'cfg', 'describe', 'lock', 'plan', 'apply', 'repo', '-h', '--help', '--version') - $backend = Get-Command -Name @('pload.exe', 'pload.cmd') -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1 + $commands = @('new', 'init', 'i', 'rm', 'remove', 'del', 'delete', 'list', 'ls', 'path', 'p', 'shell-init', 'shell', 'python', 'py', 'config', 'cfg', 'describe', 'lock', 'plan', 'apply', 'repo', 'remote', '-h', '--help', '--version') + $backend = Get-Command -Name pload -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1 if (-not $backend) { throw 'pload executable not found on PATH' } if ($PloadArgs.Count -eq 0) { & $backend.Source @@ -991,12 +998,42 @@ def _guided_new(config): def run(argv=None): raw_args = list(sys.argv[1:] if argv is None else argv) + if raw_args and raw_args[0] == "__complete": + from pload.completion import emit + + try: + return emit(build_parser(), raw_args[1:]) + except PloadError: + return 0 if not raw_args: render_landing() return 0 if any(item in HELP_FLAGS for item in raw_args): render_help(raw_args) return 0 + if (len(raw_args) == 1 and raw_args[0] not in COMMAND_NAMES + and not raw_args[0].startswith("-")): + # Activation runs inside the caller's shell function. Reaching the + # executable with an environment selector means that function is absent + # (or was bypassed); argparse's "invalid choice" hides the real problem. + try: + VenvManager(ConfigManager()).resolve_existing(raw_args[0]) + except PloadError: + pass + else: + shell = Path(os.environ.get("SHELL", "")).name + if os.name == "nt": + setup = "Invoke-Expression (& pload shell-init powershell | Out-String)" + elif shell == "fish": + setup = "command pload shell-init fish | source" + else: + shell = shell if shell in {"bash", "zsh"} else "bash" + setup = f'eval "$(command pload shell-init {shell})"' + raise PloadError( + "shell activation is not initialized in this terminal. " + "Run the following command in this terminal, then retry activation:\n" + + setup + ) args = build_parser().parse_args(raw_args) command = COMMAND_NAMES.get(args.command, args.command) config = ConfigManager(args.home, args.venvs_dir, args.state_dir) diff --git a/src/pload/completion.py b/src/pload/completion.py new file mode 100644 index 0000000..23d54e8 --- /dev/null +++ b/src/pload/completion.py @@ -0,0 +1,419 @@ +"""Read-only, local completion shared by all supported shells. + +The CLI parser supplies command/option structure. Dynamic candidates come from +registries and local directories; Tab never probes interpreters or repositories. +""" + +import argparse +import json +import shlex +from pathlib import Path + +from pload.managers.platform import ConfigManager +from pload.managers.pyversion import PythonManager + +SHELLS = ("bash", "zsh", "fish", "powershell") +CONFIG_KEYS = ( + "home", "bin-dir", "venvs-dir", "state-dir", "python-dir", "source", + "mirror-url", "downloads-json-url", "pip-source", "pip-index", "shell", +) +DIRECTORY_DESTS = { + "home", "venvs_dir", "state_dir", "project_dir", "venv_dir", "path", +} + + +def _records(path, key): + try: + data = json.loads(path.read_text(encoding="utf-8")) + records = data.get(key, []) if isinstance(data, dict) else [] + return [item for item in records if isinstance(item, dict)] + except (OSError, ValueError, TypeError): + return [] + + +def _paths(prefix, directories=False, toml=False): + typed = Path(prefix).expanduser() + if prefix.startswith("~") and "/" not in prefix and "\\" not in prefix: + return [(prefix + "/", "directory")] if typed.is_dir() else [] + directory = typed if prefix.endswith(("/", "\\")) else typed.parent + stem = "" if prefix.endswith(("/", "\\")) else typed.name + if not prefix: + directory, stem = Path("."), "" + # Keep the user's relative path or ~ rather than inserting absolute paths. + head = prefix[:len(prefix) - len(stem)] if stem else prefix + try: + entries = sorted(directory.iterdir(), key=lambda item: item.name) + return [ + (head + item.name + ("/" if item.is_dir() else ""), + "directory" if item.is_dir() else "configuration file" if toml else "file") + for item in entries + if item.name.startswith(stem) + and (not item.name.startswith(".") or stem.startswith(".")) + and (not directories or item.is_dir()) + and (not toml or item.is_dir() or item.suffix == ".toml") + ] + except OSError: + return [] + + +def _environments(config): + project_environment = Path.cwd() / ".venv" + result = [(".", "activate project .venv")] if ( + not project_environment.is_symlink() and (project_environment / "pyvenv.cfg").is_file() + ) else [] + for item in _records(config.state_path / "environments.json", "environments"): + path = Path(item.get("path", "")).expanduser() + if not item.get("path") or path.is_symlink() or not (path / "pyvenv.cfg").is_file(): + continue + name, identifier = str(item.get("name") or path.name), str(item.get("id") or "") + description = str(item.get("description") or "") + for key, label in (("id", name), ("name", identifier)): + if item.get(key): + details = " - ".join(part for part in (label, description) if part) + result.append((str(item[key]), details)) + if config.venv_path.is_dir(): + known = {value for value, _ in result} + for path in config.venv_path.iterdir(): + if (path.name not in known and not path.is_symlink() + and (path / "pyvenv.cfg").is_file()): + result.append((path.name, "local environment")) + return result + + +def _pythons(config, install=False): + result = [] if install else [("current", "current Python"), ("system", "current Python")] + for item in _records(config.state_path / "python-runtimes.json", "runtimes"): + if not item.get("path") or not Path(item["path"]).is_file(): + continue + description = f"{item.get('source', 'Python')} {item.get('version', '')}".strip() + keys = ("version",) if install else ("id", "alias", "version") + for key in keys: + if item.get(key): + label = f"{item['id']} / {description}" if key == "alias" and item.get("id") else description + result.append((item[key], label)) + version = str(item.get("version", "")) + if version.count(".") >= 2: + result.append((".".join(version.split(".")[:2]), "Python minor version")) + return result + + +def _packages(config, environment): + from packaging.utils import InvalidWheelFilename, parse_wheel_filename + + result = [] + for path in (config.home / "cache" / "wheels").glob("*.whl"): + try: + name, _, _, _ = parse_wheel_filename(path.name) + result.append((str(name), "cached package")) + except InvalidWheelFilename: + continue + # Inspect metadata directory names only; never import packages or run pip. + if environment == ".": + root = Path.cwd() / ".venv" + else: + record = next((item for item in _records( + config.state_path / "environments.json", "environments" + ) if environment in (item.get("id"), item.get("name"))), None) + if record and record.get("path"): + root = Path(record["path"]).expanduser() + elif "/" in environment or "\\" in environment or Path(environment).is_absolute(): + root = Path(environment).expanduser() + else: + root = config.venv_path / environment + if root.is_symlink() or not (root / "pyvenv.cfg").is_file(): + return result + for pattern in ("lib/python*/site-packages/*.dist-info", "Lib/site-packages/*.dist-info"): + for path in root.glob(pattern): + name = path.name[:-len(".dist-info")].rsplit("-", 1)[0].replace("_", "-") + result.append((name, "installed package")) + return result + + +def _values(action, prefix, values, config): + if action.dest == "sources": + head, _, fragment = prefix.rpartition(",") + used = set(head.split(",")) if head else set() + return [(f"{head}," + value if head else value, "Python source type") + for value in (*PythonManager.SOURCES, *PythonManager.SOURCE_ALIASES) + if value not in used and value.startswith(fragment)] + if action.choices: + return [(str(value), action.help or "") for value in action.choices] + dest = action.dest + if dest == "python_version" or dest == "version": + return _pythons(config, install=values.get("python_command") == "install") + ( + _paths(prefix) if "/" in prefix or prefix.startswith("~") else [] + ) + if dest in {"names", "envs", "environment"} or ( + dest == "name" and values.get("command") == "path" + ): + return _environments(config) + (_paths(prefix, directories=True) if prefix else []) + if dest == "source": # describe SOURCE + return _environments(config) + _paths(prefix) + if dest == "file": + return _paths(prefix, toml=True) + if dest in DIRECTORY_DESTS: + return _paths(prefix, directories=True) + if dest == "output": + return _paths(prefix, toml=True) + if dest == "location": + return _paths(prefix, directories=True) if ":" not in prefix else [] + if dest == "repository" or (dest == "name" and values.get("repo_command") == "remove"): + return [(name, "artifact repository") for name in config.settings.get("repositories", {})] + if dest == "key" and values.get("action") == "set": + return [(key, "configuration setting") for key in CONFIG_KEYS] + if dest == "value" and values.get("action") == "set": + key = values.get("key") + choices = { + "source": ("official", "ustc", "custom"), + "pip-source": ("official", "tsinghua", "ustc", "aliyun", "custom"), + "shell": SHELLS + ("none",), + } + if key in choices: + return [(value, "configuration value") for value in choices[key]] + if key in {"home", "bin-dir", "venvs-dir", "state-dir", "python-dir"}: + return _paths(prefix, directories=True) + if key == "downloads-json-url": + return _paths(prefix) + if dest in {"requirements", "package"}: + return _packages(config, values.get("environment", ".")) + return [] + + +def candidates(parser, words, index): + """Return (value, description) suggestions at a zero-based shell word index.""" + if index < 1 or index > len(words): + return [] + prefix = words[index] if index < len(words) else "" + values, overrides = {}, {} + pending = None + position = 0 + options_done = False + for word in words[1:index]: + option = parser._option_string_actions.get(word.split("=", 1)[0]) + if word == "--" and not options_done: + options_done = True + pending = None + continue + if pending is not None and (option is None or options_done): + values[pending.dest] = word + if pending.dest in {"home", "venvs_dir", "state_dir"}: + overrides[pending.dest] = word + if pending.nargs not in ("+", "*"): + pending = None + continue + if option is not None and not options_done: + pending = option if option.nargs != 0 else None + if "=" in word and pending: + value = word.split("=", 1)[1] + values[pending.dest] = value + if pending.dest in {"home", "venvs_dir", "state_dir"}: + overrides[pending.dest] = value + pending = None + continue + positional = [action for action in parser._actions if not action.option_strings] + if position >= len(positional): + continue + action = positional[position] + if isinstance(action, argparse._SubParsersAction): + if word in action.choices: + values[action.dest] = word + parser = action.choices[word] + position = 0 + else: + values[action.dest] = word + if action.nargs not in ("+", "*"): + position += 1 + + # Share the CLI's canonical names, including all short command aliases. + from pload.cli import COMMAND_NAMES, PYTHON_COMMAND_NAMES + + values["command"] = COMMAND_NAMES.get(values.get("command"), values.get("command")) + values["python_command"] = PYTHON_COMMAND_NAMES.get( + values.get("python_command"), values.get("python_command") + ) + config = ConfigManager(**overrides) + attached = "" + if "=" in prefix and prefix.startswith("--"): + name, value = prefix.split("=", 1) + option = parser._option_string_actions.get(name) + if option and option.nargs != 0: + pending, attached, prefix = option, name + "=", value + + if pending is not None and (not prefix.startswith("-") or attached): + result = _values(pending, prefix, values, config) + elif prefix.startswith("-") and not options_done: + result = [(flag, action.help or "") + for flag, action in parser._option_string_actions.items()] + if "-h" in words[:index] or "--help" in words[:index]: + result += [("-d", "detailed help with examples"), + ("--detailed", "detailed help with examples")] + else: + positional = [action for action in parser._actions if not action.option_strings] + action = positional[position] if position < len(positional) else None + if isinstance(action, argparse._SubParsersAction): + result = [(name, subparser.description or name) + for name, subparser in action.choices.items()] + if not prefix: + canonical = (COMMAND_NAMES if action.dest == "command" + else PYTHON_COMMAND_NAMES if action.dest == "python_command" else {}) + result = [(name, description) for name, description in result + if not canonical or canonical.get(name) == name] + if action.dest == "command" and index == 1: + environments = _environments(config) + if not prefix: + environments = [(value, description) for value, description in environments + if value == "." or value.startswith("v") and value[1:].isdigit()] + result += environments + if "/" in prefix or "\\" in prefix or prefix.startswith("~"): + result += _paths(prefix, directories=True) + elif action: + result = _values(action, prefix, values, config) + else: + result = [] + unique = {} + for value, description in result: + if not isinstance(value, str) or not value.startswith(prefix): + continue + if any(ord(char) < 32 or ord(char) == 127 for char in value): + continue + unique[attached + value] = " ".join(str(description).split())[:180] + return list(unique.items()) + + +def emit(parser, argv): + """Internal protocol: index, words (including pload); TSV suggestions only.""" + try: + unquote = bool(argv and argv[0] == "--unquote") + if unquote: + argv = argv[1:] + index = int(argv[0]) + words = [_unquote(word) for word in argv[1:]] if unquote else argv[1:] + for value, description in candidates(parser, words, index): + print(f"{value}\t{description}") + except (OSError, ValueError, TypeError, IndexError): + return 0 + return 0 + + +def _unquote(word): + # COMP_WORDS may contain shell quoting. Parse it as data, never with eval. + # A token at the cursor can have an opening quote without its closing one. + for ending in ("", '"', "'"): + try: + parsed = shlex.split(word + ending, comments=False) + if len(parsed) == 1: + return parsed[0] + except ValueError: + continue + return word + + +def shell_completion(shell): + if shell == "bash": + return r''' +_pload_complete() { + local value description part fragment trim logical i last trim_length + local -a tokens + tokens=() + # Bash versions differ in how COMP_WORDS splits = and :. Readline replaces + # only the fragment after these separators, so normalize and trim locally. + for ((i=0; i<=COMP_CWORD; i++)); do + part=${COMP_WORDS[i]} + last=$((${#tokens[@]} - 1)) + if ((last >= 0)) && { [[ "$part" == '=' || "$part" == ':' ]] || + [[ "${tokens[last]}" == *= || "${tokens[last]}" == *: ]]; }; then + tokens[last]+=$part + else + tokens+=("$part") + fi + done + last=$((${#tokens[@]} - 1)) + logical=${tokens[last]} + fragment=${COMP_WORDS[COMP_CWORD]} + [[ "$COMP_WORDBREAKS" == *'='* ]] && fragment=${fragment##*=} + [[ "$COMP_WORDBREAKS" == *':'* ]] && fragment=${fragment##*:} + trim_length=$((${#logical} - ${#fragment})) + trim=${logical:0:trim_length} + COMPREPLY=() + while IFS=$'\t' read -r value description; do + value=${value#"$trim"} + COMPREPLY+=("$value") + done < <(command pload __complete --unquote "$last" "${tokens[@]}" 2>/dev/null) +} +complete -o filenames -F _pload_complete pload +''' + if shell == "zsh": + return r''' +_pload_complete() { + local value description + local -a matches directories + while IFS=$'\t' read -r value description; do + [[ -z "$value" ]] && continue + if [[ "$value" == */ ]]; then + directories+=("$value") + else + matches+=("$value") + fi + done < <(command pload __complete --unquote "$((CURRENT - 1))" "${words[@]}" 2>/dev/null) + (( ${#matches} )) && compadd -- "${matches[@]}" + (( ${#directories} )) && compadd -S '' -- "${directories[@]}" + return 0 +} +if ! (( $+functions[compdef] )); then + autoload -Uz compinit + compinit -i +fi +compdef _pload_complete pload +''' + if shell == "fish": + return r''' +function __pload_complete + set -l tokens (commandline -opc) + set -l current (commandline -ct) + set -l unescaped (string unescape -- "$current" 2>/dev/null) + if test $status -eq 0 + set current "$unescaped" + else if string match -qr "^[\"']" -- "$current" + set current (string sub -s 2 -- "$current") + end + command pload __complete (count $tokens) $tokens "$current" 2>/dev/null +end +complete -c pload -e +complete -c pload -f -a '(__pload_complete)' +''' + return r''' +function __pload_completion_results { + param($wordToComplete, $commandAst, $cursorPosition) + if (-not $cursorPosition) { $cursorPosition = $commandAst.Extent.EndOffset } + $words = @($commandAst.CommandElements | Where-Object { + $_.Extent.StartOffset -lt $cursorPosition + } | ForEach-Object { + if ($_ -is [System.Management.Automation.Language.StringConstantExpressionAst]) { + $_.Value + } else { $_.Extent.Text } + }) + $index = $words.Count + if ($wordToComplete) { + $index-- + $words[$index] = $wordToComplete + } + $backend = Get-Command -Name pload -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1 + if (-not $backend) { return } + & $backend.Source __complete $index @words 2>$null | ForEach-Object { + $parts = $_ -split "`t", 2 + $value = $parts[0] + $text = $value + if ($value -match '[^a-zA-Z0-9_./:\\-]') { $text = "'" + $value.Replace("'", "''") + "'" } + [System.Management.Automation.CompletionResult]::new( + $text, $value, 'ParameterValue', $parts[1]) + } +} +Register-ArgumentCompleter -CommandName pload -ParameterName PloadArgs -ScriptBlock { + param($commandName, $parameterName, $wordToComplete, $commandAst, $fakeBoundParameters) + __pload_completion_results $wordToComplete $commandAst 0 +} +Register-ArgumentCompleter -Native -CommandName pload -ScriptBlock { + param($wordToComplete, $commandAst, $cursorPosition) + __pload_completion_results $wordToComplete $commandAst $cursorPosition +} +''' diff --git a/src/pload/help_content.py b/src/pload/help_content.py index 8e56d82..be1d3ef 100644 --- a/src/pload/help_content.py +++ b/src/pload/help_content.py @@ -213,7 +213,7 @@ the returned activation script in the current shell. """, ("shell-init",): r""" -# Enable activation in the current shell +# Enable activation and Tab completion in the current shell ```bash eval "$(pload shell-init bash)" @@ -228,6 +228,13 @@ shell's active environment. Printing the integration code has no side effect by itself; a profile changes only when the installer is explicitly asked to update one or when you add the command manually. + +Press Tab after `pload v` to complete environment IDs, after `pload new -v py` +to complete Python IDs, or after `pload py` to complete Python subcommands. +Options, their fixed choices, repository names, directories, and TOML files +are completed in the appropriate context. New environments appear immediately. +Run `pload py ls` to refresh Python ID and alias suggestions. Completion reads +local state only; it never runs package downloads or SSH searches. """, ("python",): r""" # Find or install Python runtimes diff --git a/src/pload/installer.py b/src/pload/installer.py index 57998f2..15f81f5 100644 --- a/src/pload/installer.py +++ b/src/pload/installer.py @@ -626,6 +626,32 @@ def print_welcome_screen(version, launcher, settings, profile=None): ui.logo(output=output) output.print() ui.success(f"pload {version} is ready", detail="Private runtime and launcher installed") + if profile: + ui.heading("Enable activation in this terminal", output=output) + output.print( + " The shell profile was updated. Run these commands once in this terminal " + "to activate environments immediately:" + ) + shell = settings["shell"] + bin_dir = settings["bin_dir"] + if shell == "fish": + commands = [ + f"set -gx PATH {shlex.quote(bin_dir)} $PATH", + "command pload shell-init fish | source", + ] + elif shell == "powershell": + quoted_bin = bin_dir.replace("'", "''") + commands = [ + f"$env:Path = '{quoted_bin};' + $env:Path", + "Invoke-Expression (& pload shell-init powershell | Out-String)", + ] + else: + commands = [ + f'export PATH={shlex.quote(bin_dir)}:"$PATH"', + f'eval "$(command pload shell-init {shell})"', + ] + for command in commands: + output.print(" " + command, markup=False, highlight=False, soft_wrap=True) ui.heading("Next steps", output=output) output.print(" [cyan]1[/] Check configuration [bold]pload cfg[/]") output.print(" [cyan]2[/] Find Python versions [bold]pload python list[/]") diff --git a/tests/test_completion.py b/tests/test_completion.py new file mode 100644 index 0000000..846c872 --- /dev/null +++ b/tests/test_completion.py @@ -0,0 +1,285 @@ +import argparse +import json +import os +import shutil +import subprocess +import sys +from pathlib import Path + +import pytest + +from pload.cli import build_parser, main +from pload.completion import candidates +from pload.installer import write_launcher +from pload.settings import save_settings + + +@pytest.fixture +def completion_home(tmp_path, monkeypatch): + home = tmp_path / "data" + monkeypatch.setenv("PLOAD_HOME", str(home)) + monkeypatch.delenv("PLOAD_VENVS_DIR", raising=False) + monkeypatch.delenv("PLOAD_STATE_DIR", raising=False) + save_settings(home, {"repositories": {"lab": {"kind": "ssh", "location": "host:/data"}}}) + state = home / "state" + state.mkdir() + environment = home / "venvs" / "data-tools" + environment.mkdir(parents=True) + (environment / "pyvenv.cfg").touch() + (state / "environments.json").write_text(json.dumps({"environments": [{ + "id": "v3", "name": "data-tools", "path": str(environment), + "description": "Data analysis", + }]}), encoding="utf-8") + (state / "python-runtimes.json").write_text(json.dumps({"runtimes": [{ + "id": "py2", "alias": "uv-v3.12.8", "version": "3.12.8", "source": "uv", + "path": sys.executable, + }]}), encoding="utf-8") + return home + + +def complete(*args): + return dict(candidates(build_parser(), ["pload", *args], len(args))) + + +@pytest.mark.parametrize(("words", "expected"), [ + (("",), {"new", "python", "remote", "v3"}), + (("v",), {"v3"}), + (("py", ""), {"install", "list", "path"}), + (("new", "-v", "py"), {"py2"}), + (("new", "--version=py"), {"--version=py2"}), + (("init", "--version", "uv"), {"uv-v3.12.8"}), + (("py", "p", "py"), {"py2"}), + (("py", "install", "3."), {"3.12", "3.12.8"}), + (("py", "ls", "-f", "uv,c"), {"uv,conda"}), + (("py", "ls", "--filter", ""), {"uv", "conda", "sys"}), + (("new", "--package-strategy", ""), {"auto", "custom"}), + (("rm", "v"), {"v3"}), + (("rm", "-n", "v3", "data"), {"data-tools"}), + (("path", ""), {"v3", "data-tools"}), + (("path", "v3", "--shell", ""), {"bash", "zsh", "fish", "powershell"}), + (("describe", "v"), {"v3"}), + (("remote", "add", "numpy", "--from", "v"), {"v3"}), + (("remote", "add", "numpy", "--remote", ""), {"lab"}), + (("repo", "remove", ""), {"lab"}), + (("cfg", ""), {"show", "set"}), + (("cfg", "set", "pip-"), {"pip-source", "pip-index"}), + (("cfg", "set", "pip-source", ""), {"official", "tsinghua", "aliyun", "ustc"}), + (("shell", "z"), {"zsh"}), + (("new", "--"), {"--name", "--version", "--message", "--package-strategy"}), + (("new", "-h", "-"), {"-d", "--detailed"}), +]) +def test_contextual_completion(completion_home, words, expected): + result = complete(*words) + assert expected <= result.keys() + assert all(item.startswith(words[-1]) for item in result) + + +def test_new_names_and_descriptions_are_free_text(completion_home): + assert complete("new", "--name", "") == {} + assert complete("new", "-m", "") == {} + assert "py2" not in complete("py", "install", "") + + +def test_every_command_and_alias_exposes_all_of_its_options(completion_home): + def visit(parser, words): + offered = complete(*words, "-") + assert set(parser._option_string_actions) <= offered.keys(), words + for action in parser._actions: + if isinstance(action, argparse._SubParsersAction): + for name, child in action.choices.items(): + visit(child, [*words, name]) + + visit(build_parser(), []) + + +def test_completion_uses_overridden_roots_and_is_read_only(completion_home, tmp_path, monkeypatch): + other = tmp_path / "other root" + (other / "fresh").mkdir(parents=True) + (other / "fresh" / "pyvenv.cfg").touch() + before = {path: path.read_bytes() for path in completion_home.rglob("*") if path.is_file()} + + def forbid(*args, **kwargs): + pytest.fail("completion must not execute tools, probe Python, or contact remote resources") + + monkeypatch.setattr(subprocess, "run", forbid) + assert "fresh" in complete("--venvs-dir", str(other), "rm", "fr") + assert "v3" in complete("v") + assert "py2" in complete("new", "-v", "py") + after = {path: path.read_bytes() for path in completion_home.rglob("*") if path.is_file()} + assert before == after + + +def test_candidates_refresh_after_create_and_remove(completion_home): + path = completion_home / "venvs" / "fresh" + assert "fresh" not in complete("") + path.mkdir() + marker = path / "pyvenv.cfg" + marker.touch() + assert "fresh" in complete("fr") + marker.unlink() + assert "fresh" not in complete("fr") + + +def test_package_completion_does_not_register_discovered_environments(completion_home): + environment = completion_home / "venvs" / "discovered" + packages = environment / "lib" / "python3.12" / "site-packages" + packages.mkdir(parents=True) + (environment / "pyvenv.cfg").touch() + (packages / "my_package-1.0.dist-info").mkdir() + registry = completion_home / "state" / "environments.json" + before = registry.read_bytes() + assert "my-package" in complete( + "remote", "add", "--from", "discovered", "my" + ) + assert registry.read_bytes() == before + + +def test_paths_with_spaces_and_config_files(completion_home, tmp_path, monkeypatch): + monkeypatch.chdir(tmp_path) + (tmp_path / "my project").mkdir() + (tmp_path / "my project" / "pload.toml").touch() + (tmp_path / "plain.txt").touch() + assert "my project/" in complete("init", "-P", "my") + assert "./my project/" in complete("./my") + assert "my project/pload.toml" in complete("apply", "my project/") + assert "plain.txt" not in complete("plan", "") + + +def test_completion_protocol_never_prints_help(completion_home, capsys): + assert main(["__complete", "3", "pload", "new", "-h", "-"]) == 0 + output = capsys.readouterr() + assert "--detailed\t" in output.out + assert "USAGE" not in output.out + assert not output.err + assert main(["__complete", "bad"]) == 0 + assert capsys.readouterr().out == "" + + +def test_default_completion_is_short_and_options_are_explicit(completion_home, tmp_path, monkeypatch): + monkeypatch.chdir(tmp_path) + root = complete("") + assert "new" in root and "v3" in root + assert "ls" not in root and "data-tools" not in root and "." not in root + assert not any(value.startswith("-") for value in root) + assert complete("new", "") == {} + assert "--name" in complete("new", "-") + assert "ls" in complete("l") and "data-tools" in complete("data") + (tmp_path / ".venv").mkdir() + (tmp_path / ".venv" / "pyvenv.cfg").touch() + assert "." in complete("") + + +@pytest.mark.parametrize("prefix", ["my\\ project/ch", "'my project/ch", '"my project/ch']) +def test_shell_quoted_paths_are_parsed_without_evaluation( + completion_home, tmp_path, monkeypatch, capsys, prefix, +): + monkeypatch.chdir(tmp_path) + (tmp_path / "my project" / "child folder").mkdir(parents=True) + assert main(["__complete", "--unquote", "3", "pload", "init", "-P", prefix]) == 0 + assert "my project/child folder/\t" in capsys.readouterr().out + + +@pytest.mark.parametrize("shell", ["bash", "zsh"]) +def test_registered_shell_completion_reads_live_candidates(completion_home, tmp_path, shell): + executable = shutil.which(shell) + if os.name == "nt" or not executable: + pytest.skip(f"{shell} unavailable") + bin_dir = tmp_path / "bin" + write_launcher({"home": str(completion_home), "bin_dir": str(bin_dir)}, Path(sys.executable)) + env = os.environ.copy() + env["PATH"] = str(bin_dir) + os.pathsep + env["PATH"] + env["PYTHONPATH"] = str(Path(__file__).resolve().parents[1] / "src") + env["ZDOTDIR"] = str(tmp_path) + env["PLOAD_COMPLETION_TEST_ROOT"] = str(tmp_path) + (tmp_path / "my project" / "child folder").mkdir(parents=True) + if shell == "bash": + script = r''' +set -e +eval "$(command pload shell-init bash)" +complete -p pload +COMP_WORDS=(pload new -v py) +COMP_CWORD=3 +_pload_complete +printf '%s\n' "${COMPREPLY[@]}" +COMP_WORDS=(pload v) +COMP_CWORD=1 +_pload_complete +printf '%s\n' "${COMPREPLY[@]}" +# Readline must not insert --version= twice. Cover both Bash token layouts. +COMP_WORDBREAKS='=:' +COMP_WORDS=(pload new --version=py) +COMP_CWORD=2 +_pload_complete +test "${COMPREPLY[0]}" = py2 +COMP_WORDS=(pload new --version = py) +COMP_CWORD=4 +_pload_complete +test "${COMPREPLY[0]}" = py2 +COMP_WORDS=(pload init -P "$PLOAD_COMPLETION_TEST_ROOT/my\\ project/ch") +COMP_CWORD=3 +_pload_complete +test "${COMPREPLY[0]}" = "$PLOAD_COMPLETION_TEST_ROOT/my project/child folder/" +''' + else: + script = r''' +set -e +eval "$(command pload shell-init zsh)" +test "${_comps[pload]}" = _pload_complete +# Capture arguments passed to zsh's native completion engine. +compadd() { print -rl -- "$@"; } +words=(pload new -v py) +CURRENT=4 +_pload_complete +words=(pload v) +CURRENT=2 +_pload_complete +words=(pload init -P "$PLOAD_COMPLETION_TEST_ROOT/my\\ project/ch") +CURRENT=4 +_pload_complete +''' + result = subprocess.run( + [executable, "-f" if shell == "zsh" else "--noprofile", "-c", script], + env=env, capture_output=True, text=True, check=False, timeout=30, + ) + assert result.returncode == 0, result.stdout + result.stderr + assert "py2" in result.stdout.splitlines() + assert "v3" in result.stdout.splitlines() + if shell == "zsh": + assert "-d" not in result.stdout.splitlines() + assert "-X" not in result.stdout.splitlines() + + +@pytest.mark.parametrize("shell", ["fish", "pwsh"]) +def test_other_shells_native_completion(completion_home, tmp_path, shell): + executable = shutil.which(shell) + if not executable: + pytest.skip(f"{shell} unavailable") + bin_dir = tmp_path / "bin" + write_launcher({"home": str(completion_home), "bin_dir": str(bin_dir)}, Path(sys.executable)) + env = os.environ.copy() + env["PATH"] = str(bin_dir) + os.pathsep + env["PATH"] + env["PYTHONPATH"] = str(Path(__file__).resolve().parents[1] / "src") + if shell == "fish": + script = """ +command pload shell-init fish | source +complete -C 'pload new -v py' +complete -C 'pload v' +""" + command = [executable, "--no-config", "-c", script] + else: + script = """ +$ErrorActionPreference = 'Stop' +$backend = Get-Command pload -CommandType Application | Select-Object -First 1 +Invoke-Expression ((& $backend.Source shell-init powershell) -join "`n") +$line = 'pload new -v py' +(TabExpansion2 -inputScript $line -cursorColumn $line.Length).CompletionMatches | ForEach-Object { $_.ListItemText } +$line = 'pload v' +(TabExpansion2 -inputScript $line -cursorColumn $line.Length).CompletionMatches | ForEach-Object { $_.ListItemText } +""" + command = [executable, "-NoProfile", "-NonInteractive", "-Command", script] + result = subprocess.run( + command, env=env, capture_output=True, text=True, check=False, timeout=30, + ) + assert result.returncode == 0, result.stdout + result.stderr + values = {line.split("\t", 1)[0] for line in result.stdout.splitlines()} + assert {"py2", "v3"} <= values diff --git a/tests/test_installer.py b/tests/test_installer.py index 6ee9d44..2899887 100644 --- a/tests/test_installer.py +++ b/tests/test_installer.py @@ -237,3 +237,16 @@ def test_post_install_welcome_screen_contains_ascii_and_next_steps(capsys, tmp_p assert "____" in output assert "pload cfg" in output assert "pload new -n data -v 3.12" in output + + +def test_post_install_explains_current_terminal_activation(capsys, tmp_path): + settings = collect_settings(installer_args(tmp_path, shell="zsh")) + installer.print_welcome_screen( + "1.2.0", Path(settings["bin_dir"]) / "pload", settings, + profile=tmp_path / ".zshrc", + ) + + output = capsys.readouterr().out + assert "Enable activation in this terminal" in output + assert 'eval "$(command pload shell-init zsh)"' in output + assert 'export PATH=' in output diff --git a/tests/test_shell_activation.py b/tests/test_shell_activation.py new file mode 100644 index 0000000..b3bff38 --- /dev/null +++ b/tests/test_shell_activation.py @@ -0,0 +1,67 @@ +"""Exercise activation in a persistent shell, through the installed launcher.""" + +import os +import shutil +import subprocess +import sys +from pathlib import Path + +import pytest + +from pload.installer import write_launcher + + +@pytest.mark.parametrize("shell", ["bash", "zsh"]) +def test_create_and_switch_environments_without_restarting_shell(tmp_path, shell): + executable = shutil.which(shell) + if os.name == "nt" or not executable: + pytest.skip(f"{shell} is unavailable") + + home = tmp_path / "pload data" + bin_dir = tmp_path / "bin" + write_launcher({"home": str(home), "bin_dir": str(bin_dir)}, Path(sys.executable)) + env = os.environ.copy() + env["PATH"] = str(bin_dir) + os.pathsep + env["PATH"] + env["PYTHONPATH"] = str(Path(__file__).resolve().parents[1] / "src") + env["PLOAD_VENVS_DIR"] = str(home / "venvs") + env["PLOAD_STATE_DIR"] = str(home / "state") + env["NO_COLOR"] = "1" + env["PLOAD_NO_PROGRESS"] = "1" + env["SHELL"] = executable + env.pop("VIRTUAL_ENV", None) + script = r''' +set -eu +# Reproduce a just-installed terminal: the launcher works but no function exists. +pload new -n first +if pload first 2>missing-name.txt; then exit 1; fi +if pload v1 2>missing-id.txt; then exit 1; fi +test -z "${VIRTUAL_ENV-}" +# Initialize in place, without restarting the shell. +eval "$(command pload shell-init "$1")" +pload first +test "$VIRTUAL_ENV" = "$PLOAD_VENVS_DIR/first" +python -c 'import os, sys; assert sys.prefix == os.environ["VIRTUAL_ENV"]' +# Create and activate a second environment while the first is still active. +pload new -n second +pload v2 +test "$VIRTUAL_ENV" = "$PLOAD_VENVS_DIR/second" +python -c 'import os, sys; assert sys.prefix == os.environ["VIRTUAL_ENV"]' +deactivate +pload v1 +test "$VIRTUAL_ENV" = "$PLOAD_VENVS_DIR/first" +deactivate +pload init +pload . +test "$VIRTUAL_ENV" = "$PWD/.venv" +python -c 'import os, sys; assert sys.prefix == os.environ["VIRTUAL_ENV"]' +''' + result = subprocess.run( + [executable, "-f" if shell == "zsh" else "--noprofile", "-c", script, + "shell-activation-test", shell], + cwd=tmp_path, env=env, capture_output=True, text=True, timeout=120, check=False, + ) + assert result.returncode == 0, result.stdout + result.stderr + for filename in ("missing-name.txt", "missing-id.txt"): + error = (tmp_path / filename).read_text(encoding="utf-8") + assert "shell activation is not initialized in this terminal" in error + assert f'eval "$(command pload shell-init {shell})"' in error