From 1c9be1009e216fc1e70c0e567d25962de4c9dc57 Mon Sep 17 00:00:00 2001 From: sepehrrasooli Date: Wed, 13 Aug 2025 08:56:52 +0330 Subject: [PATCH 1/9] Add usage to completion.py --- src/pip/_internal/commands/completion.py | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/pip/_internal/commands/completion.py b/src/pip/_internal/commands/completion.py index 6d9597bdea0..28edb20cd3d 100644 --- a/src/pip/_internal/commands/completion.py +++ b/src/pip/_internal/commands/completion.py @@ -81,6 +81,8 @@ class CompletionCommand(Command): """A helper command to be used for command completion.""" ignore_require_venv = True + usage = """ + %prog [options]""" def add_options(self) -> None: self.cmd_opts.add_option( From 1799410aa5f199ac669ec2d1ccf682bfc35d6761 Mon Sep 17 00:00:00 2001 From: sepehrrasooli Date: Wed, 13 Aug 2025 08:57:06 +0330 Subject: [PATCH 2/9] Add pip completion documentation --- docs/html/cli/pip_completion.rst | 74 ++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 docs/html/cli/pip_completion.rst diff --git a/docs/html/cli/pip_completion.rst b/docs/html/cli/pip_completion.rst new file mode 100644 index 00000000000..5c8e9c84049 --- /dev/null +++ b/docs/html/cli/pip_completion.rst @@ -0,0 +1,74 @@ +.. _`pip completion`: + +============== +pip completion +============== + + +Usage +===== + +.. tab:: Unix/macOS + + .. pip-command-usage:: completion "python -m pip" + +.. tab:: Windows + + .. pip-command-usage:: completion "py -m pip" + + +Description +=========== + +.. pip-command-description:: completion + +Options +======= + +.. pip-command-options:: completion + +Examples +======== + +Enable bash completion: + +.. code-block:: console + + $ python -m pip completion --bash + # pip bash completion start + _pip_completion() + { + COMPREPLY=( $( COMP_WORDS="${COMP_WORDS[*]}" \ + COMP_CWORD=$COMP_CWORD \ + PIP_AUTO_COMPLETE=1 $1 2>/dev/null ) ) + } + complete -o default -F _pip_completion /usr/bin/python -m pip + # pip bash completion end + +Enable PowerShell completion: + +.. code-block:: console + + > py -m pip completion --powershell + if ((Test-Path Function:\\TabExpansion) -and -not ` + (Test-Path Function:\\_pip_completeBackup)) {{ + Rename-Item Function:\\TabExpansion _pip_completeBackup + }} + function TabExpansion($line, $lastWord) {{ + $lastBlock = [regex]::Split($line, '[|;]')[-1].TrimStart() + if ($lastBlock.StartsWith("{prog} ")) {{ + $Env:COMP_WORDS=$lastBlock + $Env:COMP_CWORD=$lastBlock.Split().Length - 1 + $Env:PIP_AUTO_COMPLETE=1 + (& {prog}).Split() + Remove-Item Env:COMP_WORDS + Remove-Item Env:COMP_CWORD + Remove-Item Env:PIP_AUTO_COMPLETE + }} + elseif (Test-Path Function:\\_pip_completeBackup) {{ + # Fall back on existing tab expansion + _pip_completeBackup $line $lastWord + }} + }} + + \ No newline at end of file From f422ffe1129fa720b8b3003269e4560200feac50 Mon Sep 17 00:00:00 2001 From: sepehrrasooli Date: Wed, 13 Aug 2025 08:57:17 +0330 Subject: [PATCH 3/9] Add pip completion documentation to index.md --- docs/html/cli/index.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/html/cli/index.md b/docs/html/cli/index.md index a3aef3b10ba..57b15e59525 100644 --- a/docs/html/cli/index.md +++ b/docs/html/cli/index.md @@ -30,6 +30,13 @@ pip_check pip_lock ``` +```{toctree} +:maxdepth: 1 +:caption: Command-line usability and shell integration + +pip_completion +``` + ```{toctree} :maxdepth: 1 :caption: Handling Distribution Files From 28ce75e7e1681e9fefadd8483d7bf7245dba84aa Mon Sep 17 00:00:00 2001 From: sepehrrasooli Date: Wed, 13 Aug 2025 09:01:10 +0330 Subject: [PATCH 4/9] Add news entry --- news/13536.doc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 news/13536.doc.rst diff --git a/news/13536.doc.rst b/news/13536.doc.rst new file mode 100644 index 00000000000..dd010f168d5 --- /dev/null +++ b/news/13536.doc.rst @@ -0,0 +1 @@ +Add `pip completion` documentation. From 23f26cba27026ca451bc413b41da1685ddc54dfb Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Sun, 24 Aug 2025 03:39:37 +0000 Subject: [PATCH 5/9] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/html/cli/pip_completion.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/html/cli/pip_completion.rst b/docs/html/cli/pip_completion.rst index 5c8e9c84049..31d40a1510d 100644 --- a/docs/html/cli/pip_completion.rst +++ b/docs/html/cli/pip_completion.rst @@ -71,4 +71,4 @@ Enable PowerShell completion: }} }} - \ No newline at end of file + From 3b2d24d2143e85cd5c43eae4215b268172d1e17b Mon Sep 17 00:00:00 2001 From: Sepehr Rasouli Date: Sun, 24 Aug 2025 07:12:34 +0330 Subject: [PATCH 6/9] Update 13536.doc.rst --- news/13536.doc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/news/13536.doc.rst b/news/13536.doc.rst index dd010f168d5..c8e25d1ad14 100644 --- a/news/13536.doc.rst +++ b/news/13536.doc.rst @@ -1 +1 @@ -Add `pip completion` documentation. +Add ``pip completion`` documentation. From 392f2033400b15563aff5523b134e3951ec0e4f6 Mon Sep 17 00:00:00 2001 From: Sepehr Rasouli Date: Sun, 24 Aug 2025 07:35:01 +0330 Subject: [PATCH 7/9] Update pip_completion.rst --- docs/html/cli/pip_completion.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/html/cli/pip_completion.rst b/docs/html/cli/pip_completion.rst index 31d40a1510d..6131811a45b 100644 --- a/docs/html/cli/pip_completion.rst +++ b/docs/html/cli/pip_completion.rst @@ -70,5 +70,3 @@ Enable PowerShell completion: _pip_completeBackup $line $lastWord }} }} - - From 9c8b02dc703aaef9ca5a1d6718fabd326358c4d9 Mon Sep 17 00:00:00 2001 From: sepehrrasooli Date: Mon, 22 Sep 2025 16:49:28 +0330 Subject: [PATCH 8/9] Update pip completion documentation --- docs/html/cli/pip_completion.rst | 78 ++++++++++++++------------------ 1 file changed, 35 insertions(+), 43 deletions(-) diff --git a/docs/html/cli/pip_completion.rst b/docs/html/cli/pip_completion.rst index 6131811a45b..fe874ea0285 100644 --- a/docs/html/cli/pip_completion.rst +++ b/docs/html/cli/pip_completion.rst @@ -27,46 +27,38 @@ Options .. pip-command-options:: completion -Examples -======== - -Enable bash completion: - -.. code-block:: console - - $ python -m pip completion --bash - # pip bash completion start - _pip_completion() - { - COMPREPLY=( $( COMP_WORDS="${COMP_WORDS[*]}" \ - COMP_CWORD=$COMP_CWORD \ - PIP_AUTO_COMPLETE=1 $1 2>/dev/null ) ) - } - complete -o default -F _pip_completion /usr/bin/python -m pip - # pip bash completion end - -Enable PowerShell completion: - -.. code-block:: console - - > py -m pip completion --powershell - if ((Test-Path Function:\\TabExpansion) -and -not ` - (Test-Path Function:\\_pip_completeBackup)) {{ - Rename-Item Function:\\TabExpansion _pip_completeBackup - }} - function TabExpansion($line, $lastWord) {{ - $lastBlock = [regex]::Split($line, '[|;]')[-1].TrimStart() - if ($lastBlock.StartsWith("{prog} ")) {{ - $Env:COMP_WORDS=$lastBlock - $Env:COMP_CWORD=$lastBlock.Split().Length - 1 - $Env:PIP_AUTO_COMPLETE=1 - (& {prog}).Split() - Remove-Item Env:COMP_WORDS - Remove-Item Env:COMP_CWORD - Remove-Item Env:PIP_AUTO_COMPLETE - }} - elseif (Test-Path Function:\\_pip_completeBackup) {{ - # Fall back on existing tab expansion - _pip_completeBackup $line $lastWord - }} - }} + +Example Setups +============== + +Enable pip tab completion in your shell: + +.. tab:: Bash + + Add the following line to your ~/.bashrc: + + .. code-block:: console + + echo 'eval "$(python -m pip completion --bash)"' >> ~/.bashrc + + Then reload your shell or run ``source ~/.bashrc`` to enable it immediately. + +.. tab:: Zsh + + Add the following line to your ~/.zshrc: + + .. code-block:: console + + echo 'eval "$(python -m pip completion --zsh)"' >> ~/.zshrc + + Reload your shell or run ``source ~/.zshrc``. + +.. tab:: PowerShell + + Add the following line to your PowerShell profile: + + .. code-block:: powershell + + python -m pip completion --powershell | Out-String | Invoke-Expression + + Restart your PowerShell session for the changes to take effect. From e1627609e6df90c49303854cdf50d41d98d3b0aa Mon Sep 17 00:00:00 2001 From: sepehrrasooli Date: Tue, 23 Sep 2025 08:09:12 +0330 Subject: [PATCH 9/9] Add note --- docs/html/cli/pip_completion.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/html/cli/pip_completion.rst b/docs/html/cli/pip_completion.rst index fe874ea0285..3476db3b70e 100644 --- a/docs/html/cli/pip_completion.rst +++ b/docs/html/cli/pip_completion.rst @@ -62,3 +62,11 @@ Enable pip tab completion in your shell: python -m pip completion --powershell | Out-String | Invoke-Expression Restart your PowerShell session for the changes to take effect. + + .. note:: + + On Windows, ``pip.exe`` may point to a specific Python installation + (e.g. ``C:\Users\\AppData\Local\Programs\Python\Python313\python.exe -m pip``). + In this case, tab completion works for that exact command. To enable + completion for the ``pip`` command itself in PowerShell, you can use + ``Register-ArgumentCompleter`` with ``CommandName pip``.