[PATCH] Update documentation for Python packaging changes

[PATCH] Update documentation for Python packaging changes

[Ross Burton]

A number of classes and variables have been renamed, so update the
documentation as needed.

Signed-off-by: Ross Burton <ross.burton@arm.com>
---
 documentation/ref-manual/classes.rst   | 45 ++++++++++++++++----------
 documentation/ref-manual/variables.rst | 28 ++++------------
 2 files changed, 35 insertions(+), 38 deletions(-)

diff --git a/documentation/ref-manual/classes.rst b/documentation/ref-manual/classes.rst
index cba9793332..ef869e4cc1 100644
--- a/documentation/ref-manual/classes.rst
+++ b/documentation/ref-manual/classes.rst
@@ -634,7 +634,7 @@ Python modules built with ``flit_core.buildapi`` are pure Python (no
 ``C`` or ``Rust`` extensions).
 
 The resulting ``wheel`` (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__)
-is installed with the :ref:`pip_install_wheel <ref-classes-pip_install_wheel>` class.
+is installed with the :ref:`python_pep517 <ref-classes-python_pep517>` class.
 
 .. _ref-classes-fontcache:
 
@@ -1996,25 +1996,20 @@ When inherited by a recipe, the ``perlnative`` class supports using the
 native version of Perl built by the build system rather than using the
 version provided by the build host.
 
-.. _ref-classes-pip_install_wheel:
+.. _ref-classes-python_pep517:
 
-``pip_install_wheel.bbclass``
+``python_pep517.bbclass``
 =============================
 
-The ``pip_install_wheel`` class uses ``pip`` to install a Python ``wheel``
-binary archive format (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__)
+The ``python_pep517`` class installs a Python ``wheel`` binary archive (see
+`PEP-517 <https://peps.python.org/pep-0517/>`__).
 
 The Python ``wheel`` can be built with several classes, including :ref:`flit_core <ref-classes-flit_core>`,
 :ref:`setuptools_build_meta <ref-classes-setuptools_build_meta>`, and :ref:`setuptools3 <ref-classes-setuptools3>`.
 
-The absolute path to the built ``wheel`` to be installed is defined by :term:`PYPA_WHEEL` which can be
-overriden for recipes where the filename or version number of the wheel are not easily
-determined by the defaults. Other variables which can be used to customize the behavior
-of the ``pip_install_wheel`` class include:
-
-- :term:`PIP_INSTALL_ARGS`
-- :term:`PIP_INSTALL_PACKAGE`
-- :term:`PIP_INSTALL_DIST_PATH`
+The path to the wheel to be installed is defined by :term:`PEP517_WHEEL_PATH`.
+This defaults to ``${D}/dist`` and should be respected by the builder class
+(such as :ref:`flit_core <ref-classes-flit_core>`).
 
 .. _ref-classes-pixbufcache:
 
@@ -2386,7 +2381,7 @@ Python modules built with ``setuptools.build_meta`` can be pure Python or
 include ``C`` or ``Rust`` extensions).
 
 The resulting ``wheel`` (See `PEP-427 <https://www.python.org/dev/peps/pep-0427/>`__)
-is installed with the :ref:`pip_install_wheel <ref-classes-pip_install_wheel>` class.
+is installed with the :ref:`python_pep517 <ref-classes-python_pep517>` class.
 
 .. _ref-classes-setuptools3:
 
@@ -2411,9 +2406,25 @@ uses these build systems, the recipe needs to inherit the ``setuptools3`` class.
 
    .. note::
 
-     The ``setuptools3`` class ``do_install()`` task now calls ``pip install``
-     to install the ``wheel`` binary archive. In current versions of
-     ``setuptools`` the legacy ``setup.py install`` method is deprecated.
+     The ``setuptools3`` class ``do_install()`` task now installs the ``wheel``
+     binary archive. In current versions of ``setuptools`` the legacy ``setup.py
+     install`` method is deprecated. If the ``setup.py`` cannot be used with
+     wheels, for example it creates files outside of the Python module or
+     standard entry points, then :ref:`setuptools3_legacy
+     <ref-classes-setuptools3_legacy>` should be used.
+
+.. _ref-classes-setuptools3_legacy:
+
+``setuptools3_legacy.bbclass``
+==============================
+
+The ``setuptools3_legacy`` class supports Python version 3.x extensions that use
+build systems based on ``setuptools`` (e.g. only have a ``setup.py`` and have
+not migrated to the official ``pyproject.toml`` format). Unlike
+``setuptools3.bbclass``, this uses the traditional ``setup.py`` ``build`` and
+``install`` commands and not wheels. This use of ``setuptools`` like this is
+`deprecated <https://github.com/pypa/setuptools/blob/main/CHANGES.rst#v5830>`_
+but still relatively common.
 
 .. _ref-classes-setuptools3-base:
 
diff --git a/documentation/ref-manual/variables.rst b/documentation/ref-manual/variables.rst
index 005456f0c4..d08e6cf0ec 100644
--- a/documentation/ref-manual/variables.rst
+++ b/documentation/ref-manual/variables.rst
@@ -5569,6 +5569,12 @@ system and gives an overview of their function and contents.
 
       :term:`PE` is the default value of the :term:`PKGE` variable.
 
+   :term:`PEP517_WHEEL_PATH`
+      When used by recipes that inherit the
+      :ref:`python_pep517 <ref-classes-python_pep517>` class,
+      denotes the path to ``dist/`` (short for distribution) where the
+      binary archive ``wheel`` is built.
+
    :term:`PF`
       Specifies the recipe or package name and includes all version and
       revision numbers (i.e. ``glibc-2.13-r20+svnr15508/`` and
@@ -5577,23 +5583,10 @@ system and gives an overview of their function and contents.
 
    :term:`PIP_INSTALL_ARGS`
       When used by recipes that inherit the
-      :ref:`pip_install_wheel <ref-classes-pip_install_wheel>` class,
+      :ref:`python_pep517 <ref-classes-python_pep517>` class,
       denotes the arguments passed to ``pip install`` to adjust the
       behavior of how the ``wheel`` is installed.
 
-   :term:`PIP_INSTALL_DIST_PATH`
-      When used by recipes that inherit the
-      :ref:`pip_install_wheel <ref-classes-pip_install_wheel>` class,
-      denotes the path to ``dist/`` (short for distribution) where the
-      binary archive ``wheel`` is built. This is used in part to create
-      the :term:`PYPA_WHEEL` variable.
-
-   :term:`PIP_INSTALL_PACKAGE`
-      When used by recipes that inherit the
-      :ref:`pip_install_wheel <ref-classes-pip_install_wheel>` class,
-      denotes the name of the package portion of the ``wheel`` filename.
-      This is used in part to create the :term:`PYPA_WHEEL` variable.
-
    :term:`PIXBUF_PACKAGES`
       When inheriting the :ref:`pixbufcache <ref-classes-pixbufcache>`
       class, this variable identifies packages that contain the pixbuf
@@ -6021,13 +6014,6 @@ system and gives an overview of their function and contents.
 
       :term:`PV` is the default value of the :term:`PKGV` variable.
 
-   :term:`PYPA_WHEEL`
-      When used by recipes that inherit the
-      :ref:`pip_install_wheel <ref-classes-pip_install_wheel>` class, denotes
-      the absolute path to the built ``wheel`` to be installed. Normally the
-      defaults which use :term:`PIP_INSTALL_PACKAGE` and :term:`PIP_INSTALL_DIST_PATH`
-      to build the path to the ``wheel`` should be sufficient.
-
    :term:`PYTHON_ABI`
       When used by recipes that inherit the
       :ref:`setuptools3 <ref-classes-setuptools3>` class, denotes the
-- 
2.25.1

Re: [docs] [PATCH] Update documentation for Python packaging changes

[Michael Opdenacker]

Hi Ross,

On 3/14/22 18:07, Ross Burton wrote:
> A number of classes and variables have been renamed, so update the
> documentation as needed.


Many thanks for the update!
Reviewed-by: Michael Opdenacker <michael.opdenacker@bootlin.com>
... and merged into master-next.
Cheers
Michael.

-- 
Michael Opdenacker, Bootlin
Embedded Linux and Kernel engineering
https://bootlin.com