Add docs

Author: dukecat0

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
+```

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

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"

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,38 +34,38 @@ 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
 
 
 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