From 9a82bdfc527391bb306fc70814977a14e184f946 Mon Sep 17 00:00:00 2001 From: Matthew Feickert Date: Mon, 20 Feb 2023 19:25:04 -0700 Subject: [PATCH 1/2] Quote extras to guard shells with glob qualifiers * Shells like zsh have glob qualifiers that will error if an extra is not quoted. While the glob qualifiers can be disabled, adding quotes guards against errors if people are copy-pasting or do not know that they can disable the behavior. * Use single quotes for Linux/Mac and use double quotes for Windows to follow existing style conventions. --- docs/html/cli/pip_install.rst | 18 +++++++++--------- news/11842.doc.rst | 2 ++ 2 files changed, 11 insertions(+), 9 deletions(-) create mode 100644 news/11842.doc.rst diff --git a/docs/html/cli/pip_install.rst b/docs/html/cli/pip_install.rst index 7c17c264a30..6e517c0fd04 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] @ 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 '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]" 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. diff --git a/news/11842.doc.rst b/news/11842.doc.rst new file mode 100644 index 00000000000..bd063996f54 --- /dev/null +++ b/news/11842.doc.rst @@ -0,0 +1,2 @@ +Quote extras in the pip install docs to guard shells with default glob +qualifiers, like zsh. From ced45695a08b3bfdb240b016e8cfcd72b0a3a56c Mon Sep 17 00:00:00 2001 From: Matthew Feickert Date: Mon, 6 Mar 2023 00:26:29 -0600 Subject: [PATCH 2/2] Quote all install command components that aren't a bare package name * As a means to make things easier for new users, quote everything in a `pip install` command that is part of a package that isn't just a bare package name. * Use single quotes for Linux/Mac and use double quotes for Windows to follow existing style conventions. --- docs/html/cli/pip_install.rst | 48 +++++++++++++++++------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/html/cli/pip_install.rst b/docs/html/cli/pip_install.rst index 6e517c0fd04..951dc2705a3 100644 --- a/docs/html/cli/pip_install.rst +++ b/docs/html/cli/pip_install.rst @@ -11,7 +11,7 @@ Usage .. tab:: Unix/macOS - .. pip-command-usage:: install "python -m pip" + .. pip-command-usage:: install 'python -m pip' .. tab:: Windows @@ -277,7 +277,7 @@ Examples .. code-block:: shell python -m pip install SomePackage # latest version - python -m pip install SomePackage==1.0.4 # specific version + python -m pip install 'SomePackage==1.0.4' # specific version python -m pip install 'SomePackage>=1.0.4' # minimum version .. tab:: Windows @@ -285,8 +285,8 @@ Examples .. code-block:: shell py -m pip install SomePackage # latest version - py -m pip install SomePackage==1.0.4 # specific version - py -m pip install 'SomePackage>=1.0.4' # minimum version + py -m pip install "SomePackage==1.0.4" # specific version + py -m pip install "SomePackage>=1.0.4" # minimum version #. Install a list of requirements specified in a file. See the :ref:`Requirements files `. @@ -349,13 +349,13 @@ Examples .. code-block:: shell - python -m pip install SomeProject@git+https://git.repo/some_pkg.git@1.3.1 + python -m pip install 'SomeProject@git+https://git.repo/some_pkg.git@1.3.1' .. tab:: Windows .. code-block:: shell - py -m pip install SomeProject@git+https://git.repo/some_pkg.git@1.3.1 + py -m pip install "SomeProject@git+https://git.repo/some_pkg.git@1.3.1" #. Install a project from VCS in "editable" mode. See the sections on :doc:`../topics/vcs-support` and :ref:`Editable Installs `. @@ -364,20 +364,20 @@ Examples .. code-block:: shell - python -m pip install -e git+https://git.repo/some_pkg.git#egg=SomePackage # from git - python -m pip install -e hg+https://hg.repo/some_pkg.git#egg=SomePackage # from mercurial - python -m pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage # from svn - python -m pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomePackage # from 'feature' branch - python -m pip install -e "git+https://git.repo/some_repo.git#egg=subdir&subdirectory=subdir_path" # install a python package from a repo subdirectory + python -m pip install -e 'git+https://git.repo/some_pkg.git#egg=SomePackage' # from git + python -m pip install -e 'hg+https://hg.repo/some_pkg.git#egg=SomePackage' # from mercurial + python -m pip install -e 'svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage' # from svn + python -m pip install -e 'git+https://git.repo/some_pkg.git@feature#egg=SomePackage' # from 'feature' branch + python -m pip install -e 'git+https://git.repo/some_repo.git#egg=subdir&subdirectory=subdir_path' # install a python package from a repo subdirectory .. tab:: Windows .. code-block:: shell - py -m pip install -e git+https://git.repo/some_pkg.git#egg=SomePackage # from git - py -m pip install -e hg+https://hg.repo/some_pkg.git#egg=SomePackage # from mercurial - py -m pip install -e svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage # from svn - py -m pip install -e git+https://git.repo/some_pkg.git@feature#egg=SomePackage # from 'feature' branch + py -m pip install -e "git+https://git.repo/some_pkg.git#egg=SomePackage" # from git + py -m pip install -e "hg+https://hg.repo/some_pkg.git#egg=SomePackage" # from mercurial + py -m pip install -e "svn+svn://svn.repo/some_pkg/trunk/#egg=SomePackage" # from svn + py -m pip install -e "git+https://git.repo/some_pkg.git@feature#egg=SomePackage" # from 'feature' branch py -m pip install -e "git+https://git.repo/some_repo.git#egg=subdir&subdirectory=subdir_path" # install a python package from a repo subdirectory #. Install a package with `extras`_. @@ -408,15 +408,15 @@ Examples .. code-block:: shell - python -m pip install ./downloads/SomePackage-1.0.4.tar.gz - python -m pip install http://my.package.repo/SomePackage-1.0.4.zip + python -m pip install './downloads/SomePackage-1.0.4.tar.gz' + python -m pip install 'http://my.package.repo/SomePackage-1.0.4.zip' .. tab:: Windows .. code-block:: shell - py -m pip install ./downloads/SomePackage-1.0.4.tar.gz - py -m pip install http://my.package.repo/SomePackage-1.0.4.zip + py -m pip install "./downloads/SomePackage-1.0.4.tar.gz" + py -m pip install "http://my.package.repo/SomePackage-1.0.4.zip" #. Install a particular source archive file following :pep:`440` direct references. @@ -424,17 +424,17 @@ Examples .. code-block:: shell - python -m pip install SomeProject@http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl - python -m pip install "SomeProject @ http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl" - python -m pip install SomeProject@http://my.package.repo/1.2.3.tar.gz + python -m pip install 'SomeProject@http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl' + python -m pip install 'SomeProject @ http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl' + python -m pip install 'SomeProject@http://my.package.repo/1.2.3.tar.gz' .. tab:: Windows .. code-block:: shell - py -m pip install SomeProject@http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl + py -m pip install "SomeProject@http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl" py -m pip install "SomeProject @ http://my.package.repo/SomeProject-1.2.3-py33-none-any.whl" - py -m pip install SomeProject@http://my.package.repo/1.2.3.tar.gz + py -m pip install "SomeProject@http://my.package.repo/1.2.3.tar.gz" #. Install from alternative package repositories.