From 809dffe24df4d557eb7893fa2c93826c9dfc9186 Mon Sep 17 00:00:00 2001 From: meowmeow Date: Sat, 24 Aug 2024 10:57:55 +0000 Subject: [PATCH] Add docs --- docs/backend.md | 34 ++++++++++++++++++++++++++++++++++ docs/examples.md | 2 ++ mkdocs.yml | 1 + tests/test_backend.py | 21 ++++++++++----------- 4 files changed, 47 insertions(+), 11 deletions(-) create mode 100644 docs/backend.md diff --git a/docs/backend.md b/docs/backend.md new file mode 100644 index 0000000000..2f0667e96f --- /dev/null +++ b/docs/backend.md @@ -0,0 +1,34 @@ +Starting from version 1.8.0, pipx supports different backends and installers. + +### Backends supported: +- `venv` (Default) +- `uv` (via `uv venv`) +- `virtualenv` + +### Installers supported: +- `pip` (Default) +- `uv` (via `uv pip`) + +If you wish to use a different backend or installer, you can either: + +- Pass command line arguments (`--backend`, `--installer`) +- Set envirionment variables (`PIPX_DEFAULT_BACKEND`, `PIPX_DEFAULT_INSTALLER`) + +> [!NOTE] +> Command line arguments always have higher precedence than environment variables. + +### Examples +```bash +# Use uv as backend and installer +pipx install --backend uv --installer uv black + +# Use virtualenv as backend and uv as installer +pipx install --backend virtualenv --installer uv black +``` + +Use environment variables to set backend and installer: +```bash +export PIPX_DEFAULT_BACKEND=uv +export PIPX_DEFAULT_INSTALLER=uv +pipx install black +``` \ No newline at end of file diff --git a/docs/examples.md b/docs/examples.md index 2c79c54830..7dfd63f2a3 100644 --- a/docs/examples.md +++ b/docs/examples.md @@ -21,6 +21,7 @@ pipx install --index-url https://test.pypi.org/simple/ --pip-args='--extra-index pipx --global install pycowsay pipx install . pipx install path/to/some-project +pipx install --backend uv --installer uv black ``` ## `pipx run` examples @@ -41,6 +42,7 @@ pipx run pycowsay --version # prints pycowsay version pipx run --python pythonX pycowsay pipx run pycowsay==2.0 --version pipx run pycowsay[dev] --version +pipx run --backend uv --installer uv pycowsay pipx run --spec git+https://github.com/psf/black.git black pipx run --spec git+https://github.com/psf/black.git@branch-name black pipx run --spec git+https://github.com/psf/black.git@git-hash black diff --git a/mkdocs.yml b/mkdocs.yml index 4962e750d6..170f73ea61 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -31,6 +31,7 @@ nav: - Getting Started: "getting-started.md" - Docs: "docs.md" - Troubleshooting: "troubleshooting.md" + - Backend: "backend.md" - Examples: "examples.md" - Comparison to Other Tools: "comparisons.md" - How pipx works: "how-pipx-works.md" diff --git a/tests/test_backend.py b/tests/test_backend.py index 7ee18fbfce..21d1cb1deb 100644 --- a/tests/test_backend.py +++ b/tests/test_backend.py @@ -1,7 +1,6 @@ import os -from helpers import run_pipx_cli -from package_info import _exe_if_win +from helpers import run_pipx_cli, WIN def test_custom_backend_venv(pipx_temp_env, capsys, caplog): @@ -14,14 +13,14 @@ def test_custom_backend_venv(pipx_temp_env, capsys, caplog): def test_custom_backend_virtualenv(pipx_temp_env, capsys, caplog): assert not run_pipx_cli(["install", "--backend", "virtualenv", "nox"]) captured = capsys.readouterr() - assert f"{_exe_if_win("virtualenv")} --python" in caplog.text + assert "virtualenv" in caplog.text assert "installed package" in captured.out def test_custom_backend_uv(pipx_temp_env, capsys, caplog): assert not run_pipx_cli(["install", "--backend", "uv", "pylint"]) captured = capsys.readouterr() - assert f"{_exe_if_win("uv")} venv" in caplog.text + assert "uv" in caplog.text assert "installed package" in captured.out @@ -35,15 +34,15 @@ def test_custom_installer_pip(pipx_temp_env, capsys, caplog): def test_custom_installer_uv(pipx_temp_env, capsys, caplog): assert not run_pipx_cli(["install", "--installer", "uv", "sphinx"]) captured = capsys.readouterr() - assert f"{_exe_if_win("uv")} pip install" in caplog.text + assert "uv" in caplog.text assert "installed package" in captured.out def test_custom_installer_backend_uv(pipx_temp_env, capsys, caplog): assert not run_pipx_cli(["install", "--installer", "uv", "--backend", "uv", "black"]) captured = capsys.readouterr() - assert f"{_exe_if_win("uv")} venv" in caplog.text - assert f"{_exe_if_win("uv")} pip install" in caplog.text + assert f"{'uv.EXE' if WIN else 'uv'} venv" in caplog.text + assert "uv pip install" in caplog.text assert "installed package" in captured.out @@ -51,22 +50,22 @@ def test_custom_installer_uv_backend_venv(pipx_temp_env, capsys, caplog): assert not run_pipx_cli(["install", "--installer", "uv", "--backend", "venv", "nox"]) captured = capsys.readouterr() assert "-m venv --without-pip" in caplog.text - assert f"{_exe_if_win("uv")} pip install" in caplog.text + assert f"{'uv.EXE' if WIN else 'uv'} pip install" in caplog.text assert "installed package" in captured.out def test_custom_installer_uv_backend_virtualenv(pipx_temp_env, capsys, caplog): assert not run_pipx_cli(["install", "--installer", "uv", "--backend", "virtualenv", "pylint"]) captured = capsys.readouterr() - assert f"{_exe_if_win("virtualenv")} --python" in caplog.text - assert f"{_exe_if_win("uv")} pip install" in caplog.text + assert "virtualenv" in caplog.text + assert f"{'uv.EXE' if WIN else 'uv'} pip install" in caplog.text assert "installed package" in captured.out def test_custom_installer_pip_backend_uv(pipx_temp_env, capsys, caplog): assert not run_pipx_cli(["install", "--installer", "pip", "--backend", "uv", "nox"]) captured = capsys.readouterr() - assert f"{_exe_if_win("uv")} venv" in caplog.text + assert f"{'uv.EXE' if WIN else 'uv'} venv" in caplog.text assert "-m pip" in caplog.text assert "installed package" in captured.out