Merge remote-tracking branch 'upstream/main'

.github/ISSUE_TEMPLATE/bug-report.yml

@@ -61,11 +61,13 @@ body:
       description: >-
         Provide the output of the steps above, including the commands
         themselves and pip's output/traceback etc.
+        (The output will auto-rendered as code, no need for backticks.)
 
         If you want to present output from multiple commands, please prefix
         the line containing the command with `$ `. Please also ensure that
         the "How to reproduce" section contains matching instructions for
         reproducing this.
+      render: shell
 
   - type: checkboxes
     attributes:

.pre-commit-config.yaml

@@ -2,7 +2,7 @@ exclude: 'src/pip/_vendor/'
 
 repos:
 - repo: https://github.com/pre-commit/pre-commit-hooks
-  rev: v4.5.0
+  rev: v4.6.0
   hooks:
   - id: check-builtin-literals
   - id: check-added-large-files
@@ -17,18 +17,18 @@ repos:
     exclude: .patch
 
 - repo: https://github.com/psf/black-pre-commit-mirror
-  rev: 23.12.1
+  rev: 24.4.0
   hooks:
   - id: black
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.2.0
+  rev: v0.4.1
   hooks:
     - id: ruff
       args: [--fix, --exit-non-zero-on-fix]
 
 - repo: https://github.com/pre-commit/mirrors-mypy
-  rev: v1.8.0
+  rev: v1.9.0
   hooks:
   - id: mypy
     exclude: tests/data

AUTHORS.txt

@@ -445,7 +445,7 @@ Mark Williams
 Markus Hametner
 Martey Dodoo
 Martin Fischer
-Martin Häcker
+Martin Häcker
 Martin Pavlasek
 Masaki
 Masklinn
@@ -495,7 +495,7 @@ Miro Hrončok
 Monica Baluna
 montefra
 Monty Taylor
-Muha Ajjan‮
+Muha Ajjan
 Nadav Wexler
 Nahuel Ambrosini
 Nate Coraor
@@ -757,4 +757,3 @@ Zvezdan Petkovic
 Łukasz Langa
 Роман Донченко
 Семён Марьясин
-‮rekcäH nitraM‮

README.rst

@@ -1,18 +1,20 @@
 pip - The Python Package Installer
 ==================================
 
-.. image:: https://img.shields.io/pypi/v/pip.svg
+.. |pypi-version| image:: https://img.shields.io/pypi/v/pip.svg
    :target: https://pypi.org/project/pip/
    :alt: PyPI
 
-.. image:: https://img.shields.io/pypi/pyversions/pip
+.. |python-versions| image:: https://img.shields.io/pypi/pyversions/pip
    :target: https://pypi.org/project/pip
    :alt: PyPI - Python Version
 
-.. image:: https://readthedocs.org/projects/pip/badge/?version=latest
+.. |docs-badge| image:: https://readthedocs.org/projects/pip/badge/?version=latest
    :target: https://pip.pypa.io/en/latest
    :alt: Documentation
 
+|pypi-version| |python-versions| |docs-badge|
+
 pip is the `package installer`_ for Python. You can use pip to install packages from the `Python Package Index`_ and other indexes.
 
 Please take a look at our documentation for how to install and use pip:

docs/html/cli/pip_install.rst

@@ -212,11 +212,12 @@ and `there <https://www.python.org/dev/peps/pep-0503/>`_.
 pip offers a number of package index options for modifying how packages are
 found.
 
-pip looks for packages in a number of places: on PyPI (if not disabled via
-``--no-index``), in the local filesystem, and in any additional repositories
-specified via ``--find-links`` or ``--index-url``. There is no ordering in
-the locations that are searched. Rather they are all checked, and the "best"
-match for the requirements (in terms of version number - see the
+pip looks for packages in a number of places: on PyPI (or the index given as
+``--index-url``, if not disabled via ``--no-index``), in the local filesystem,
+and in any additional repositories specified via ``--find-links`` or
+``--extra-index-url``. There is no priority in the locations that are searched.
+Rather they are all checked, and the "best" match for the requirements (in
+terms of version number - see the
 :ref:`specification <pypug:version-specifiers>` for details) is selected.
 
 See the :ref:`pip install Examples<pip install Examples>`.

docs/html/index.md

@@ -23,7 +23,7 @@ cli/index
 :hidden:
 
 development/index
-ux_research_design
+ux-research-design/index
 news
 Code of Conduct <https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md>
 GitHub <https://github.com/pypa/pip>

docs/html/reference/build-system/pyproject-toml.md

@@ -130,6 +130,13 @@ dealing with [the same challenges as pip has for legacy builds](build-output).
 
 ## Fallback Behaviour
 
+```{warning}
+The following snippet merely describes the fallback behavior. For valid
+examples of `pyproject.toml` to use with setuptools, please refer to
+[the setuptools documentation](
+https://setuptools.pypa.io/en/stable/userguide/quickstart.html#basic-use).
+```
+
 If a project does not have a `pyproject.toml` file containing a `build-system`
 section, it will be assumed to have the following backend settings:
 

docs/html/topics/configuration.md

@@ -118,7 +118,7 @@ then the latter value will be used.
 The names of the settings are derived from the long command line option.
 
 As an example, if you want to use a different package index (`--index-url`) and
-set the HTTP timeout (`--default-timeout`) to 60 seconds, your config file would
+set the HTTP timeout (`--timeout`) to 60 seconds, your config file would
 look like this:
 
 ```ini
@@ -205,7 +205,7 @@ pip's command line options can be set with environment variables using the
 format `PIP_<UPPER_LONG_NAME>` . Dashes (`-`) have to be replaced with
 underscores (`_`).
 
-- `PIP_DEFAULT_TIMEOUT=60` is the same as `--default-timeout=60`
+- `PIP_TIMEOUT=60` is the same as `--timeout=60`
 - ```
   PIP_FIND_LINKS="http://mirror1.example.com http://mirror2.example.com"
   ```

docs/html/user_guide.rst

@@ -856,6 +856,12 @@ We are using `freeze`_ here which outputs installed packages in requirements for
 
   reqs = subprocess.check_output([sys.executable, '-m', 'pip', 'freeze'])
 
+To programmatically monitor download progress use the ``--progress-bar=raw`` option.
+This will print lines to stdout in the format ``Progress CURRENT of TOTAL``, where
+``CURRENT`` and ``TOTAL`` are integers and the unit is bytes.
+If the real total is unknown then ``TOTAL`` is set to ``0``. Be aware that the
+specific formatting of pip's outputs are *not* guaranteed to be the same in future versions.
+
 If you don't want to use pip's command line functionality, but are rather
 trying to implement code that works with Python packages, their metadata, or
 PyPI, then you should consider other, supported, packages that offer this type
@@ -1134,6 +1140,13 @@ Since this work will not change user-visible behavior described in the
 pip documentation, this change is not covered by the :ref:`Deprecation
 Policy`.
 
+.. attention::
+
+    The legacy resolver is deprecated and unsupported. New features, such
+    as :doc:`reference/installation-report`, will not work with the
+    legacy resolver and this resolver will be removed in a future
+    release.
+
 Context and followup
 --------------------
 

docs/html/ux-research-design/contribute.md

@@ -0,0 +1,24 @@
+# How to Contribute
+
+## Participate in UX Research
+
+It is important that we hear from pip users so that we can:
+
+- Understand how pip is currently used by the Python community
+- Understand how pip users _need_ pip to behave
+- Understand how pip users _would like_ pip to behave
+- Understand pip’s strengths and shortcomings
+- Make useful design recommendations for improving pip
+
+If you are interested in participating in pip user research, please [join pip’s user panel](https://mail.python.org/mailman3/lists/pip-ux-studies.python.org/).
+
+## Test New Features
+
+You can help the team by testing new features as they are released to the community.
+
+## Report and Work on UX Issues
+
+If you believe that you have found a user experience bug in pip, or you have ideas for how pip could be made better for all users, please file an issue on the [pip issue tracker](https://github.com/pypa/pip/issues/new).
+
+You can also help improve pip’s user experience by [working on UX issues](https://github.com/pypa/pip/issues?q=is%3Aissue+label%3AUX+is%3Aopen). Issues that are ideal for new contributors are marked with “[good first issue](https://github.com/pypa/pip/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22)”. Explore the
+[UX Guidance](guidance) if you have questions.