feat: support requirements specifications in pipx run (#783)

* feat: support requirements specifications in pipx run

* docs: update examples with version pinning/extras

Author: henryiii

README.md

@@ -219,14 +219,14 @@ Any arguments after the application name will be passed directly to the applicat
 
 Re-running the same app is quick because pipx caches Virtual Environments on a per-app basis. The caches only last a few days, and when they expire, pipx will again use the latest version of the package. This way you can be sure you're always running a new version of the package without having to manually upgrade.
 
-If the app name does not match that package name, you can use the `--spec` argument:
+If the app name does not match that package name, you can use the `--spec` argument to specify the package to install and app to run separately:
 ```
 pipx run --spec PACKAGE APP
 ```
 
-You can also use the `--spec` argument to run a specific version, or use any other `pip`-specifier:
+You can also specify specific versions, version ranges, or extras:
 ```
-pipx run --spec PACKAGE==1.0.0 APP
+pipx run APP==1.0.0
 ```
 
 ### Running from Source Control

docs/changelog.md

@@ -1,5 +1,6 @@
 dev
 
+- Support `pipx run` with version constraints and extras. (#697)
 
 0.16.5
 

docs/examples.md

@@ -26,7 +26,8 @@ pipx run pycowsay moo
 pipx --version  # prints pipx version
 pipx run pycowsay --version  # prints pycowsay version
 pipx run --python pythonX pycowsay
-pipx run --spec pycowsay==2.0 pycowsay --version
+pipx run pycowsay==2.0 --version
+pipx run pycowsay[dev] --version
 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

src/pipx/main.py

@@ -16,6 +16,7 @@
 from typing import Any, Callable, Dict, List
 
 import argcomplete  # type: ignore
+from packaging.requirements import InvalidRequirement, Requirement
 from packaging.utils import canonicalize_name
 
 import pipx.constants
@@ -175,9 +176,17 @@ def run_pipx_command(args: argparse.Namespace) -> ExitCode:  # noqa: C901
             if ("spec" in args and args.spec is not None)
             else args.app_with_args[0]
         )
+        # For any package, we need to just use the name
+        try:
+            package_name = Requirement(args.app_with_args[0]).name
+        except InvalidRequirement:
+            # Raw URLs to scripts are supported, too, so continue if
+            # we can't parse this as a package
+            package_name = args.app_with_args[0]
+
         use_cache = not args.no_cache
         commands.run(
-            args.app_with_args[0],
+            package_name,
             package_or_url,
             args.app_with_args[1:],
             args.python,

tests/test_run.py

@@ -42,9 +42,12 @@ def run_pipx_cli_exit(pipx_cmd_list, assert_exit=None):
         assert sys_exit.value.code == assert_exit
 
 
+@pytest.mark.parametrize(
+    "package_name", ["pycowsay", "pycowsay==0.0.0.1", "pycowsay>=0.0.0.1"]
+)
 @mock.patch("os.execvpe", new=execvpe_mock)
-def test_simple_run(pipx_temp_env, monkeypatch, capsys):
-    run_pipx_cli_exit(["run", "pycowsay", "--help"])
+def test_simple_run(pipx_temp_env, monkeypatch, capsys, package_name):
+    run_pipx_cli_exit(["run", package_name, "--help"])
     captured = capsys.readouterr()
     assert "Download the latest version of a package" not in captured.out