add news fragment, example & test for example

changelog.d/1316.feature.md

@@ -0,0 +1,7 @@
+Add `pipx upgrade-shared` command.
+
+This allows to create/upgrade shared libraries as a standalone command.
+
+It might be useful to initialize shared libraries with a pinned version of pip in order to create e.g. reproducible docker images using a constraint file.
+
+It also allows for different `--pip-args` that one would get with the `install` command.

docs/examples.md

@@ -142,3 +142,17 @@ Installing to existing venv 'pipx'
     - pipx
 done! ✨ 🌟 ✨
 ```
+
+## `pipx upgrade-shared` examples
+
+One use of the upgrade-shared command is to force a `pip` upgrade.
+
+```shell
+> pipx upgrade-shared
+```
+
+Another use of the upgrade-shared command is to pin (temporarily) `pip` to a specific version.
+
+```shell
+> pipx upgrade-shared --pip-args='pip==24.0'
+```

testdata/tests_packages/primary_packages.txt

@@ -19,6 +19,8 @@ kaggle==1.5.16
 nox==2022.1.7
 nox[tox_to_nox]==2023.4.22
 pbr==5.6.0
+pip==23.3.2
+pip==24.0
 pip
 pycowsay==0.0.0.2
 pygdbmi==0.10.0.0

tests/test_upgrade_shared.py

@@ -1,3 +1,5 @@
+import subprocess
+
 from helpers import run_pipx_cli
 
 
@@ -39,3 +41,22 @@ def test_upgrade_shared_pip_args(pipx_ultra_temp_env, capsys, caplog, monkeypatc
     assert "Already upgraded libraries in" not in caplog.text
     assert shared_libs.has_been_updated_this_run is False
     assert shared_libs.is_valid is True
+
+
+def test_upgrade_shared_pin_pip(pipx_ultra_temp_env, capsys, caplog, monkeypatch):
+    from pipx.shared_libs import shared_libs
+
+    def pip_version():
+        cmd = "from importlib.metadata import version; print(version('pip'))"
+        ret = subprocess.run([shared_libs.python_path, "-c", cmd], check=True, capture_output=True, text=True)
+        return ret.stdout.strip()
+
+    assert shared_libs.has_been_updated_this_run is False
+    assert shared_libs.is_valid is False
+    assert run_pipx_cli(["upgrade-shared", "-v", "--pip-args='pip==24.0'"]) == 0
+    assert shared_libs.is_valid is True
+    assert pip_version() == "24.0"
+    shared_libs.has_been_updated_this_run = False  # reset for next run
+    assert run_pipx_cli(["upgrade-shared", "-v", "--pip-args='pip==23.3.2'"]) == 0
+    assert shared_libs.is_valid is True
+    assert pip_version() == "23.3.2"