add preinstall with multiple packages example, cli help and test

changelog.d/1321.doc.md

@@ -0,0 +1 @@
+Add example, test and cli help description how to install multiple packages with the --preinstall flag

docs/examples.md

@@ -11,6 +11,7 @@ pipx install git+https://github.com/psf/black.git@git-hash
 pipx install git+ssh://<username>@<private-repo-domain>/<path-to-package.git>
 pipx install https://github.com/psf/black/archive/18.9b0.zip
 pipx install black[d]
+pipx install --preinstall ansible-lint --preinstall mitogen ansible-core
 pipx install 'black[d] @ git+https://github.com/psf/black.git@branch-name'
 pipx install --suffix @branch-name 'black[d] @ git+https://github.com/psf/black.git@branch-name'
 pipx install --include-deps jupyter

src/pipx/main.py

@@ -426,7 +426,10 @@ def _add_install(subparsers: argparse._SubParsersAction, shared_parser: argparse
     p.add_argument(
         "--preinstall",
         action="append",
-        help=("Optional packages to be installed into the Virtual Environment before " "installing the main package."),
+        help=(
+            "Optional package to be installed into the Virtual Environment before "
+            "installing the main package. Use this flag multiple times if you want to preinstall multiple packages."
+        ),
     )
     add_pip_venv_args(p)
 

tests/test_install.py

@@ -338,6 +338,12 @@ def test_preinstall(pipx_temp_env, caplog):
     assert "black" in caplog.text
 
 
+def test_preinstall_multiple(pipx_temp_env, caplog):
+    assert not run_pipx_cli(["install", "--preinstall", "chardet", "--preinstall", "colorama", "nox"])
+    assert "chardet" in caplog.text
+    assert "colorama" in caplog.text
+
+
 @pytest.mark.xfail
 def test_do_not_wait_for_input(pipx_temp_env, pipx_session_shared_dir, monkeypatch):
     monkeypatch.setenv("PIP_INDEX_URL", "http://127.0.0.1:8080/simple")