docs: Use 'req@url' syntax to install from remote VCS (#2115)

* Use 'req@url' syntax when using pip to install from a remote git
  repository over 'url#egg=req' to avoid the use of #egg= fragments
  with a non-PEP 508 name. This will be required in pip v25.0+.
   - c.f. pypa/pip#11617 for more details.
* For best practice, quote the use of extras for compatibility across all shells.

Author: matthewfeickert

docs/installation.rst

@@ -32,36 +32,36 @@ Install latest stable release from `PyPI <https://pypi.org/project/pyhf/>`__...
 
 .. code-block:: console
 
-    python -m pip install pyhf[tensorflow]
+    python -m pip install 'pyhf[tensorflow]'
 
 ... with PyTorch backend
 ++++++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install pyhf[torch]
+    python -m pip install 'pyhf[torch]'
 
 ... with JAX backend
 ++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install pyhf[jax]
+    python -m pip install 'pyhf[jax]'
 
 ... with all backends
 +++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install pyhf[backends]
+    python -m pip install 'pyhf[backends]'
 
 
 ... with xml import/export functionality
 ++++++++++++++++++++++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install pyhf[xmlio]
+    python -m pip install 'pyhf[xmlio]'
 
 
 Install latest development version from `GitHub <https://github.com/scikit-hep/pyhf>`__...
@@ -72,43 +72,43 @@ Install latest development version from `GitHub <https://github.com/scikit-hep/p
 
 .. code-block:: console
 
-    python -m pip install --upgrade "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf"
+    python -m pip install --upgrade 'pyhf@git+https://github.com/scikit-hep/pyhf.git'
 
 ... with TensorFlow backend
 +++++++++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install --upgrade "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[tensorflow]"
+    python -m pip install --upgrade 'pyhf[tensorflow]@git+https://github.com/scikit-hep/pyhf.git'
 
 ... with PyTorch backend
 ++++++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install --upgrade "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[torch]"
+    python -m pip install --upgrade 'pyhf[torch]@git+https://github.com/scikit-hep/pyhf.git'
 
 ... with JAX backend
 ++++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install --upgrade "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[jax]"
+    python -m pip install --upgrade 'pyhf[jax]@git+https://github.com/scikit-hep/pyhf.git'
 
 ... with all backends
 +++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install --upgrade "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[backends]"
+    python -m pip install --upgrade 'pyhf[backends]@git+https://github.com/scikit-hep/pyhf.git'
 
 
 ... with xml import/export functionality
 ++++++++++++++++++++++++++++++++++++++++
 
 .. code-block:: console
 
-    python -m pip install --upgrade "git+https://github.com/scikit-hep/pyhf.git#egg=pyhf[xmlio]"
+    python -m pip install --upgrade 'pyhf[xmlio]@git+https://github.com/scikit-hep/pyhf.git'
 
 
 Updating :code:`pyhf`

src/pyhf/cli/complete.py

@@ -21,9 +21,9 @@ def cli(shell):
     @click.command(help='Generate shell completion code.', name='completions')
     @click.argument('shell', default=None)
     def cli(shell):
-        '''Placeholder for shell completion code generatioon function if necessary dependency is missing.'''
+        """Placeholder for shell completion code generatioon function if necessary dependency is missing."""
         click.secho(
-            'This requires the click_completion module.\n'
-            'You can install it with the shellcomplete extra:\n'
-            'python -m pip install pyhf[shellcomplete]'
+            "This requires the click_completion module.\n"
+            "You can install it with the shellcomplete extra:\n"
+            "python -m pip install 'pyhf[shellcomplete]'"
         )

src/pyhf/cli/rootio.py

@@ -50,7 +50,7 @@ def xml2json(
     except ImportError:
         log.error(
             "xml2json requires uproot, please install pyhf using the "
-            "xmlio extra: python -m pip install pyhf[xmlio]",
+            "xmlio extra: python -m pip install 'pyhf[xmlio]'",
             exc_info=True,
         )
     from pyhf import readxml
@@ -86,7 +86,7 @@ def json2xml(workspace, output_dir, specroot, dataroot, resultprefix, patch):
     except ImportError:
         log.error(
             "json2xml requires uproot, please install pyhf using the "
-            "xmlio extra: python -m pip install pyhf[xmlio]",
+            "xmlio extra: python -m pip install 'pyhf[xmlio]'",
             exc_info=True,
         )
     from pyhf import writexml

src/pyhf/contrib/cli.py

@@ -24,7 +24,7 @@ def cli():
 
         .. code-block:: shell
 
-            $ python -m pip install pyhf[contrib]
+            $ python -m pip install 'pyhf[contrib]'
     """
     from pyhf.contrib import utils  # Guard CLI from missing extra # noqa: F401
 
@@ -72,6 +72,6 @@ def download(archive_url, output_directory, verbose, force, compress):
     except AttributeError:
         log.error(
             "\nInstallation of the contrib extra is required to use the contrib CLI API"
-            + "\nPlease install with: python -m pip install pyhf[contrib]\n",
+            + "\nPlease install with: python -m pip install 'pyhf[contrib]'\n",
             exc_info=True,
         )

src/pyhf/contrib/utils.py

@@ -128,6 +128,6 @@ def download(archive_url, output_directory, force=False, compress=False):
 except ModuleNotFoundError:
     log.error(
         "\nInstallation of the contrib extra is required to use pyhf.contrib.utils.download"
-        + "\nPlease install with: python -m pip install pyhf[contrib]\n",
+        + "\nPlease install with: python -m pip install 'pyhf[contrib]'\n",
         exc_info=True,
     )

tests/test_scripts.py

@@ -632,7 +632,7 @@ def test_missing_contrib_extra(caplog):
         for line in [
             "import of requests halted; None in sys.modules",
             "Installation of the contrib extra is required to use pyhf.contrib.utils.download",
-            "Please install with: python -m pip install pyhf[contrib]",
+            "Please install with: python -m pip install 'pyhf[contrib]'",
         ]:
             assert line in caplog.text
         caplog.clear()
@@ -672,7 +672,7 @@ def test_missing_contrib_download(caplog):
             for line in [
                 "module 'pyhf.contrib.utils' has no attribute 'download'",
                 "Installation of the contrib extra is required to use the contrib CLI API",
-                "Please install with: python -m pip install pyhf[contrib]",
+                "Please install with: python -m pip install 'pyhf[contrib]'",
             ]:
                 assert line in caplog.text
             caplog.clear()