Skip to content

gh-130160: use .. program:: directive for documenting ensurepip CLI #130253

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Feb 18, 2025
Merged

gh-130160: use .. program:: directive for documenting ensurepip CLI #130253

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
64ac23b
gh-130160: use `.. program::` directive for documenting `ensurepip` CLI
Mr-Sunglasses Feb 18, 2025
ce0b24e
chore: fix lint issues
Mr-Sunglasses Feb 18, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 22 additions & 11 deletions Doc/library/ensurepip.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,8 @@ when creating a virtual environment) or after explicitly uninstalling
Command line interface
----------------------

.. program:: ensurepip

The command line interface is invoked using the interpreter's ``-m`` switch.

The simplest possible invocation is::
Expand All @@ -61,26 +63,34 @@ By default, ``pip`` is installed into the current virtual environment
active virtual environment). The installation location can be controlled
through two additional command line options:

* :samp:`--root {dir}`: Installs ``pip`` relative to the given root directory
rather than the root of the currently active virtual environment (if any)
or the default root for the current Python installation.
* ``--user``: Installs ``pip`` into the user site packages directory rather
than globally for the current Python installation (this option is not
permitted inside an active virtual environment).
.. option:: --root <dir>

Installs ``pip`` relative to the given root directory rather than the root
of the currently active virtual environment (if any) or the default root
for the current Python installation.

.. option:: --user

Installs ``pip`` into the user site packages directory rather than globally
for the current Python installation (this option is not permitted inside an
active virtual environment).

By default, the scripts ``pipX`` and ``pipX.Y`` will be installed (where
X.Y stands for the version of Python used to invoke ``ensurepip``). The
scripts installed can be controlled through two additional command line
options:

* ``--altinstall``: if an alternate installation is requested, the ``pipX``
script will *not* be installed.
.. option:: --altinstall

* ``--default-pip``: if a "default pip" installation is requested, the
``pip`` script will be installed in addition to the two regular scripts.
If an alternate installation is requested, the ``pipX`` script will *not* be
installed.

Providing both of the script selection options will trigger an exception.
.. option:: --default-pip

If a "default pip" installation is requested, the ``pip`` script will be
installed in addition to the two regular scripts.

Providing both of the script selection options will trigger an exception.

Module API
----------
Expand Down Expand Up @@ -136,3 +146,4 @@ Module API
``pip``, but other software should not assume those dependencies will
always be present by default (as the dependencies may be removed in a
future version of ``pip``).

Loading