Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 11 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,18 @@
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:

Check warning

Code scanning / CodeQL

Workflow does not contain permissions Medium

Actions job or workflow does not limit the permissions of the GITHUB_TOKEN. Consider setting an explicit permissions block, using the following as a minimal starting point: {contents: read}
strategy:
fail-fast: false
matrix:
Expand Down
20 changes: 20 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
77 changes: 57 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -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):

Expand Down Expand Up @@ -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:
Expand All @@ -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:

Expand Down Expand Up @@ -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
Expand All @@ -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,
Expand All @@ -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:

Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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:

Expand Down
2 changes: 1 addition & 1 deletion docs/declarative-environments.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
Binary file added docs/images/pload-completion-macos.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/pload-help-macos.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/pload-list-macos.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/pload-python-list-macos.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file modified docs/images/pload-welcome-macos.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
4 changes: 2 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@ 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"
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",
Expand Down
2 changes: 1 addition & 1 deletion src/pload/__init__.py
Original file line number Diff line number Diff line change
@@ -1 +1 @@
__version__ = "1.2.0b1"
__version__ = "1.2.0"
45 changes: 41 additions & 4 deletions src/pload/cli.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,6 @@
import argparse
import json
import os
import re
import sys
from pathlib import Path
Expand Down Expand Up @@ -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 "$@"
;;
*)
Expand All @@ -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 .
Expand All @@ -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
Expand Down Expand Up @@ -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)
Expand Down
Loading
Loading