From 47f1d5dc4780d5eabb33adccd0950ab0a47ab481 Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Wed, 13 Dec 2023 23:20:52 +0100 Subject: [PATCH 1/3] Improve documentation usability by turning some PEP numbers into PUG links --- NEWS.rst | 5 +++-- docs/html/cli/pip_install.rst | 21 +++++++++++-------- docs/html/cli/pip_wheel.rst | 3 ++- .../architecture/package-finding.rst | 6 +++--- docs/html/development/getting-started.rst | 1 - docs/html/reference/inspect-report.md | 5 ++--- .../html/topics/more-dependency-resolution.md | 8 +++---- docs/html/topics/vcs-support.md | 5 ++--- docs/html/user_guide.rst | 5 +++-- 9 files changed, 31 insertions(+), 28 deletions(-) diff --git a/NEWS.rst b/NEWS.rst index 26d00a3f144..20d3f89dc0d 100644 --- a/NEWS.rst +++ b/NEWS.rst @@ -96,8 +96,9 @@ Process Deprecations and Removals ------------------------- -- Deprecate legacy version and version specifiers that don't conform to `PEP 440 - `_ (`#12063 `_) +- Deprecate legacy version and version specifiers that don't conform to the + :ref:`specification `. + (`#12063 `_) - ``freeze`` no longer excludes the ``setuptools``, ``distribute``, and ``wheel`` from the output when running on Python 3.12 or later, where they are not included in a virtual environment by default. Use ``--exclude`` if you wish to diff --git a/docs/html/cli/pip_install.rst b/docs/html/cli/pip_install.rst index 35b82c05e09..2664c75223d 100644 --- a/docs/html/cli/pip_install.rst +++ b/docs/html/cli/pip_install.rst @@ -49,7 +49,7 @@ each is, in the following order: otherwise pip will report an error). 3. Local file (a sdist or wheel format archive, following the naming conventions for those formats). -4. A requirement, as specified in :pep:`440`. +4. A :ref:`version specifier `. Each item identified is added to the set of requirements to be satisfied by the install. @@ -97,7 +97,8 @@ Installation Order .. note:: This section is only about installation order of runtime dependencies, and - does not apply to build dependencies (those are specified using PEP 518). + does not apply to build dependencies (those are specified using the + :ref:`[build-system] table `). As of v6.1.0, pip installs dependencies before their dependents, i.e. in "topological order." This is the only commitment pip currently makes related @@ -181,8 +182,9 @@ Pre-release Versions -------------------- Starting with v1.4, pip will only install stable versions as specified by -`pre-releases`_ by default. If a version cannot be parsed as a compliant :pep:`440` -version then it is assumed to be a pre-release. +`pre-releases`_ by default. If a version cannot be parsed as a +:ref:`compliant ` version then it is assumed to be +a pre-release. If a Requirement specifier includes a pre-release or development version (e.g. ``>=0.0.dev0``) then pip will allow pre-release and development versions @@ -214,8 +216,8 @@ 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 :pep:`440` for -details) is selected. +match for the requirements (in terms of version number - see the +:ref:`specification ` for details) is selected. See the :ref:`pip install Examples`. @@ -380,7 +382,8 @@ Examples 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`_. +#. Install a package with extras, i.e., optional dependencies + (:ref:`specification `). .. tab:: Unix/macOS @@ -418,7 +421,8 @@ Examples 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. +#. Install a particular source archive file following direct references + (:ref:`specification `). .. tab:: Unix/macOS @@ -539,5 +543,4 @@ Examples py -m pip install SomePackage1 SomePackage2 --no-binary SomePackage1 -.. _extras: https://www.python.org/dev/peps/pep-0508/#extras .. _PyPI: https://pypi.org/ diff --git a/docs/html/cli/pip_wheel.rst b/docs/html/cli/pip_wheel.rst index bfd19a0ccb1..ba749529c0c 100644 --- a/docs/html/cli/pip_wheel.rst +++ b/docs/html/cli/pip_wheel.rst @@ -34,7 +34,8 @@ Differences to ``build`` ------------------------ `build `_ is a simple tool which can among other things build -wheels for projects using PEP 517. It is comparable to the execution of ``pip wheel --no-deps .``. +wheels for projects using the standard ``pyproject.toml``-based build interface. It +is comparable to the execution of ``pip wheel --no-deps .``. It can also build source distributions which is not possible with ``pip``. ``pip wheel`` covers the wheel scope of ``build`` but offers many additional features. diff --git a/docs/html/development/architecture/package-finding.rst b/docs/html/development/architecture/package-finding.rst index 0b64d420d93..4885d925ee3 100644 --- a/docs/html/development/architecture/package-finding.rst +++ b/docs/html/development/architecture/package-finding.rst @@ -182,8 +182,9 @@ example, whether a pre-release is eligible for selection or whether a file whose hash doesn't match is eligible depends on properties of the collection as a whole. -The ``CandidateEvaluator`` class uses information like the list of `PEP 425`_ -tags compatible with the target Python interpreter, hashes provided by the +The ``CandidateEvaluator`` class uses information like the list of +:ref:`platform tags ` +compatible with the target Python interpreter, hashes provided by the user, and other user preferences, etc. Specifically, the class has a ``get_applicable_candidates()`` method. @@ -236,5 +237,4 @@ The class is the return type of both the ``CandidateEvaluator`` class's ``find_best_candidate()`` method. -.. _`PEP 425`: https://www.python.org/dev/peps/pep-0425/ .. _`PEP 503`: https://www.python.org/dev/peps/pep-0503/ diff --git a/docs/html/development/getting-started.rst b/docs/html/development/getting-started.rst index 34d647fc231..bc483997a64 100644 --- a/docs/html/development/getting-started.rst +++ b/docs/html/development/getting-started.rst @@ -206,7 +206,6 @@ in order to start contributing. .. _`open an issue`: https://github.com/pypa/pip/issues/new?title=Trouble+with+pip+development+environment .. _`install Python`: https://realpython.com/installing-python/ -.. _`PEP 484 type-comments`: https://www.python.org/dev/peps/pep-0484/#suggested-syntax-for-python-2-7-and-straddling-code .. _`rich CLI`: https://docs.pytest.org/en/latest/usage.html#specifying-tests-selecting-tests .. _`GitHub`: https://github.com/pypa/pip .. _`good first issues`: https://github.com/pypa/pip/labels/good%20first%20issue diff --git a/docs/html/reference/inspect-report.md b/docs/html/reference/inspect-report.md index 1355e5d4274..ad8263c6742 100644 --- a/docs/html/reference/inspect-report.md +++ b/docs/html/reference/inspect-report.md @@ -27,9 +27,8 @@ The report is a JSON object with the following properties: distribution packages that are installed. - `environment`: an object describing the environment where the installation report was - generated. See [PEP 508 environment - markers](https://peps.python.org/pep-0508/#environment-markers) for more information. - Values have a string type. + generated. See the section on environment markers in the {ref}`pypug:dependency-specifiers` + specification for more information. Values have a string type. (InspectReportItem)= diff --git a/docs/html/topics/more-dependency-resolution.md b/docs/html/topics/more-dependency-resolution.md index 1c7836e5c0f..b955e2ec114 100644 --- a/docs/html/topics/more-dependency-resolution.md +++ b/docs/html/topics/more-dependency-resolution.md @@ -97,10 +97,10 @@ feeding candidates to the resolver, and has a key role to play in selecting suitable candidates. Note that the resolver is *only* relevant for packages fetched from an index. -Candidates coming from other sources (local source directories, PEP 508 -direct URL references) do *not* go through the finder, and are merged with the -candidates provided by the finder as part of the resolver's "provider" -implementation. +Candidates coming from other sources (local source directories, {ref}`direct +URL references `) do *not* go through the finder, +and are merged with the candidates provided by the finder as part of the resolver's +"provider" implementation. As well as determining what versions exist in the index for a given project, the finder selects the best distribution file to use for that candidate. This diff --git a/docs/html/topics/vcs-support.md b/docs/html/topics/vcs-support.md index 465d5ecb78c..c8169dbe24c 100644 --- a/docs/html/topics/vcs-support.md +++ b/docs/html/topics/vcs-support.md @@ -140,9 +140,8 @@ pip also looks at the `egg` fragment specifying the "project name". In practice mode. In all other circumstances, the `egg` fragment is not necessary and its use is discouraged. -The `egg` fragment **should** be a bare -[PEP 508](https://peps.python.org/pep-0508/) project name. Anything else -is not guaranteed to work. +The `egg` fragment **should** be a bare {ref}`project name `. +Anything else is not guaranteed to work. ````{admonition} Example If your repository layout is: diff --git a/docs/html/user_guide.rst b/docs/html/user_guide.rst index 9a6f2901cd5..f0cbded683d 100644 --- a/docs/html/user_guide.rst +++ b/docs/html/user_guide.rst @@ -264,7 +264,7 @@ Installing from Wheels "Wheel" is a built, archive format that can greatly speed installation compared to building and installing from source archives. For more information, see the -`Wheel docs `_ , :pep:`427`, and :pep:`425`. +:ref:`specification `. pip prefers Wheels where they are available. To disable this, use the :ref:`--no-binary ` flag for :ref:`pip install`. @@ -306,7 +306,8 @@ name: .. note:: In the future, the ``path[extras]`` syntax may become deprecated. It is - recommended to use PEP 508 syntax wherever possible. + recommended to use :ref:`standard ` + syntax wherever possible. For the cases where wheels are not available, pip offers :ref:`pip wheel` as a convenience, to build wheels for all your requirements and dependencies. From 190334606c92d5e6028b09af5dbb3102a1167035 Mon Sep 17 00:00:00 2001 From: Jean Abou Samra Date: Thu, 14 Dec 2023 22:00:33 +0100 Subject: [PATCH 2/3] Add a news entry --- news/12434.doc.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 news/12434.doc.rst diff --git a/news/12434.doc.rst b/news/12434.doc.rst new file mode 100644 index 00000000000..49a93a2841d --- /dev/null +++ b/news/12434.doc.rst @@ -0,0 +1 @@ +Replace some links to PEPs with links to the canonical specifications on https://packaging.python.org From 6fd8100bb79c3e44345744dce86d347eb3e8bb57 Mon Sep 17 00:00:00 2001 From: Jean Abou-Samra Date: Sun, 17 Dec 2023 11:35:03 +0100 Subject: [PATCH 3/3] Use intersphinx --- news/12434.doc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/news/12434.doc.rst b/news/12434.doc.rst index 49a93a2841d..c1d3635df78 100644 --- a/news/12434.doc.rst +++ b/news/12434.doc.rst @@ -1 +1 @@ -Replace some links to PEPs with links to the canonical specifications on https://packaging.python.org +Replace some links to PEPs with links to the canonical specifications on the :doc:`pypug:index`