Quote extras to avoid problems with glob qualifiers in shells

[matthewfeickert]

What's the problem this feature will solve?

Some shells, like zsh, have glob qualifiers that will error if an extra is not quoted

$ python -m pip install black[jupyter]
zsh: no matches found: black[jupyter]
$ python -m pip install --upgrade 'black[jupyter]'  # correct way without disabling globbing

Globbing can of course be turned off in these shells, but some users might not think of this right away.

At the moment all the extras in the pip install docs are unquoted:

pip/docs/html/cli/pip_install.rst

Lines 383 to 403 in 5e20a7b

	#. Install a package with `extras`_.
	.. tab:: Unix/macOS
	.. code-block:: shell
	python -m pip install SomePackage[PDF]
	python -m pip install "SomePackage[PDF] @ git+https://git.repo/SomePackage@main#subdirectory=subdir_path"
	python -m pip install .[PDF] # project in current directory
	python -m pip install SomePackage[PDF]==3.0
	python -m pip install SomePackage[PDF,EPUB] # multiple extras
	.. tab:: Windows
	.. code-block:: shell
	py -m pip install SomePackage[PDF]
	py -m pip install "SomePackage[PDF] @ git+https://git.repo/SomePackage@main#subdirectory=subdir_path"
	py -m pip install .[PDF] # project in current directory
	py -m pip install SomePackage[PDF]==3.0
	py -m pip install SomePackage[PDF,EPUB] # multiple extras

Would a contribution that quotes all these be of interest? Or as this is not necessarily required for installation of an extra should this not be added? If this is of interest, I have a branch on my fork with this done already that I can PR.

Describe the solution you'd like

Have the pip team decide if this is something they would like a docs contribution on or not. If so, then the contribution would be the following patch (or one that uses single quotes, but I was following the existing use of ")

index 7c17c264a..4b6c50264 100644
--- a/docs/html/cli/pip_install.rst
+++ b/docs/html/cli/pip_install.rst
@@ -386,21 +386,21 @@ Examples
 
       .. code-block:: shell
 
-         python -m pip install SomePackage[PDF]
+         python -m pip install "SomePackage[PDF]"
          python -m pip install "SomePackage[PDF] @ git+https://git.repo/SomePackage@main#subdirectory=subdir_path"
-         python -m pip install .[PDF]  # project in current directory
-         python -m pip install SomePackage[PDF]==3.0
-         python -m pip install SomePackage[PDF,EPUB]  # multiple extras
+         python -m pip install ".[PDF]"  # project in current directory
+         python -m pip install "SomePackage[PDF]==3.0"
+         python -m pip install "SomePackage[PDF,EPUB]"  # multiple extras
 
    .. tab:: Windows
 
       .. code-block:: shell
 
-         py -m pip install SomePackage[PDF]
+         py -m pip install "SomePackage[PDF]"
          py -m pip install "SomePackage[PDF] @ git+https://git.repo/SomePackage@main#subdirectory=subdir_path"
-         py -m pip install .[PDF]  # project in current directory
-         py -m pip install SomePackage[PDF]==3.0
-         py -m pip install SomePackage[PDF,EPUB]  # multiple extras
+         py -m pip install ".[PDF]"  # project in current directory
+         py -m pip install "SomePackage[PDF]==3.0"
+         py -m pip install "SomePackage[PDF,EPUB]"  # multiple extras
 
 #. Install a particular source archive file.
 

Alternative Solutions

Do nothing, as not quoting an extra works fine in shells like Bash that don't do globbing by default.

Additional context

This is a xref of pypa/packaging.python.org#1209

Code of Conduct

• I agree to follow the PSF Code of Conduct.

[uranusjr]

Let’s quote all the install arguments in this page to avoid confusion?

[matthewfeickert]

Let’s quote all the install arguments in this page to avoid confusion?

Hm. While that would of course work, I'm not sure that quoting

pip/docs/html/cli/pip_install.rst

Line 279 in 5e20a7b

python -m pip install SomePackage # latest version

to

python -m pip install "SomePackage"

is useful for helping avoid confusion — as you almost never see a package without a version qualifier on it being quoted I could see that it might even cause confusion.