Merge branch 'main' into discussion-downstream

Author: ncoghlan

source/guides/licensing-examples-and-user-scenarios.rst

@@ -10,6 +10,10 @@ Licensing examples and user scenarios
 license files and other legally required information.
 This document aims to provide clear guidance how to migrate from the legacy
 to the standardized way of declaring licenses.
+Make sure your preferred build backend supports :pep:`639` before
+trying to apply the newer guidelines.
+As of February 2025, :doc:`setuptools <setuptools:userguide/pyproject_config>`
+and :ref:`flit <flit:pyproject_toml_project>` don't support :pep:`639` yet.
 
 
 Licensing Examples

source/guides/writing-pyproject-toml.rst

@@ -322,9 +322,20 @@ You can also specify the format explicitly, like this:
    readme = {file = "README.txt", content-type = "text/x-rst"}
 
 
+.. _license:
+
 ``license``
 -----------
 
+:pep:`639` (accepted in August 2024) has changed the way the ``license`` field
+is declared. Make sure your preferred build backend supports :pep:`639` before
+trying to apply the newer guidelines.
+As of February 2025, :doc:`setuptools <setuptools:userguide/pyproject_config>`
+and :ref:`flit <flit:pyproject_toml_project>` don't support :pep:`639` yet.
+
+:pep:`639` license declaration
+''''''''''''''''''''''''''''''
+
 This is a valid :term:`SPDX license expression <License Expression>` consisting
 of one or more :term:`license identifiers <License Identifier>`.
 The full license list is available at the
@@ -352,10 +363,42 @@ The custom identifiers must follow the SPDX specification,
     [project]
     license = "LicenseRef-My-Custom-License"
 
+Legacy license declaration
+''''''''''''''''''''''''''
+
+This can take two forms. You can put your license in a file, typically
+:file:`LICENSE` or :file:`LICENSE.txt`, and link that file here:
+
+.. code-block:: toml
+
+    [project]
+    license = {file = "LICENSE"}
+
+or you can write the name of the license:
+
+.. code-block:: toml
+
+    [project]
+    license = {text = "MIT License"}
+
+If you are using a standard, well-known license, it is not necessary to use this
+field. Instead, you should use one of the :ref:`classifiers` starting with ``License
+::``. (As a general rule, it is a good idea to use a standard, well-known
+license, both to avoid confusion and because some organizations avoid software
+whose license is unapproved.)
+
+
+.. _license-files:
 
 ``license-files``
 -----------------
 
+:pep:`639` (accepted in August 2024) has introduced the ``license-files`` field.
+Make sure your preferred build backend supports :pep:`639` before declaring the
+field.
+As of February 2025, :doc:`setuptools <setuptools:userguide/pyproject_config>`
+and :ref:`flit <flit:pyproject_toml_project>` don't support :pep:`639` yet.
+
 This is a list of license files and files containing other legal
 information you want to distribute with your package.
 
@@ -529,7 +572,7 @@ A full example
    ]
    description = "Lovely Spam! Wonderful Spam!"
    readme = "README.rst"
-   license = "MIT"
+   license = "MIT"  # or license = {file = "LICENSE.txt"} for legacy declaration
    license-files = ["LICEN[CS]E.*"]
    keywords = ["egg", "bacon", "sausage", "tomatoes", "Lobster Thermidor"]
    classifiers = [

source/specifications/platform-compatibility-tags.rst

@@ -109,8 +109,8 @@ subset of Linux platforms, and allows building wheels tagged with the
 ``manylinux`` platform tag which can be used across most common Linux
 distributions.
 
-The current standard is the future-proof ``manylinux_x_y`` standard. It defines
-tags of the form ``manylinux_x_y_arch``, where ``x`` and ``y`` are glibc major
+The current standard is the future-proof :file:`manylinux_{x}_{y}` standard. It defines
+tags of the form :file:`manylinux_{x}_{y}_{arch}`, where ``x`` and ``y`` are glibc major
 and minor versions supported (e.g. ``manylinux_2_24_xxx`` should work on any
 distro using glibc 2.24+), and ``arch`` is the architecture, matching the value
 of :py:func:`sysconfig.get_platform()` on the system as in the "simple" form above.
@@ -151,7 +151,7 @@ auditwheel  ``>=1.0.0``     ``>=2.0.0``        ``>=3.0.0``        ``>=3.3.0`` [#
 
 The ``musllinux`` family of tags is similar to ``manylinux``, but for Linux
 platforms that use the musl_ libc rather than glibc (a prime example being Alpine
-Linux). The schema is ``musllinux_x_y_arch``, supporting musl ``x.y`` and higher
+Linux). The schema is :file:`musllinux_{x}_{y}_{arch}``, supporting musl ``x.y`` and higher
 on the architecture ``arch``.
 
 The musl version values can be obtained by executing the musl libc shared
@@ -189,6 +189,108 @@ There are currently two possible ways to find the musl library’s location that
 Python interpreter is running on, either with the system ldd_ command, or by
 parsing the ``PT_INTERP`` section’s value from the executable’s ELF_ header.
 
+.. _macos:
+
+macOS
+-----
+
+macOS uses the ``macosx`` family of tags (the ``x`` suffix is a historical
+artefact of Apple's official macOS naming scheme). The schema for compatibility
+tags is :file:`macosx_{x}_{y}_{arch}`, indicating that the wheel is compatible
+with macOS ``x.y`` or later on the architecture ``arch``.
+
+The values of ``x`` and ``y`` correspond to the major and minor version number of
+the macOS release, respectively. They must both be positive integers, with the
+``x`` value being ``>= 10``. The version number always includes a major *and*
+minor version, even if Apple's official version numbering only refers to
+the major value. For example, ``macosx_11_0_arm64`` indicates compatibility
+with macOS 11 or later.
+
+macOS binaries can be compiled for a single architecture, or can include support
+for multiple architectures in the same binary (sometimes called "fat" binaries).
+To indicate support for a single architecture, the value of ``arch`` must match
+the value of :py:func:`platform.machine()` on the system. To indicate
+support multiple architectures, the ``arch`` tag should be an identifier from
+the following list that describes the set of supported architectures:
+
+============== ========================================
+``arch``       Architectures supported
+============== ========================================
+``universal2`` ``arm64``, ``x86_64``
+``universal``  ``i386``, ``ppc``, ``ppc64``, ``x86_64``
+``intel``      ``i386``, ``x86_64``
+``fat``        ``i386``, ``ppc``
+``fat3``       ``i386``, ``ppc``, ``x86_64``
+``fat64``      ``ppc64``, ``x86_64``
+============== ========================================
+
+The minimum supported macOS version may also be constrained by architecture. For
+example, macOS 11 (Big Sur) was the first release to support arm64. These
+additional constraints are enforced transparently by the macOS compilation
+toolchain when building binaries that support multiple architectures.
+
+.. _android:
+
+Android
+-------
+
+Android uses the schema :file:`android_{apilevel}_{abi}`, indicating
+compatibility with the given Android API level or later, on the given ABI. For
+example, ``android_27_arm64_v8a`` indicates support for API level 27 or later,
+on ``arm64_v8a`` devices. Android makes no distinction between physical devices
+and emulated devices.
+
+The API level should be a positive integer. This is *not* the same thing as
+the user-facing Android version. For example, the release known as Android
+12 (code named "Snow Cone") uses API level 31 or 32, depending on the specific
+Android version in use. Android's release documentation contains the `full list
+of Android versions and their corresponding API levels
+<https://developer.android.com/tools/releases/platforms>`__.
+
+There are 4 `supported ABIs <https://developer.android.com/ndk/guides/abis>`__.
+Normalized according to the rules above, they are:
+
+* ``armeabi_v7a``
+* ``arm64_v8a``
+* ``x86``
+* ``x86_64``
+
+Virtually all current physical devices use one of the ARM architectures. ``x86``
+and ``x86_64`` are supported for use in the emulator. ``x86`` has not been
+supported as a development platform since 2020, and no new emulator images have
+been released since then.
+
+.. _ios:
+
+iOS
+---
+
+iOS uses the schema :file:`ios_{x}_{y}_{arch}_{sdk}`, indicating compatibility with
+iOS ``x.y`` or later, on the ``arch`` architecture, using the ``sdk`` SDK.
+
+The value of ``x`` and ``y`` correspond to the major and minor version number of
+the iOS release, respectively. They must both be positive integers. The version
+number always includes a major *and* minor version, even if Apple's official
+version numbering only refers to the major value. For example, a
+``ios_13_0_arm64_iphonesimulator`` indicates compatibility with iOS 13 or later.
+
+The value of ``arch`` must match the value of :py:func:`platform.machine()` on
+the system.
+
+The value of ``sdk`` must be either ``iphoneos`` (for physical devices), or
+``iphonesimulator`` (for device simulators). These SDKs have the same API
+surface, but are incompatible at the binary level, even if they are running on
+the same CPU architecture. Code compiled for an arm64 simulator will not run on
+an arm64 device.
+
+The combination of :file:`{arch}_{sdk}` is referred to as the "multiarch". There
+are three possible values for multiarch:
+
+* ``arm64_iphoneos``, for physical iPhone/iPad devices. This includes every
+  iOS device manufactured since ~2015;
+* ``arm64_iphonesimulator``, for simulators running on Apple Silicon macOS
+  hardware; and
+* ``x86_64_iphonesimulator``, for simulators running on x86_64 hardware.
 
 Use
 ===
@@ -339,7 +441,8 @@ History
 - November 2019: The ``manylinux_x_y`` perennial tag was approved through
   :pep:`600`.
 - April 2021: The ``musllinux_x_y`` tag was approved through :pep:`656`.
-
+- December 2023: The tags for iOS were approved through :pep:`730`.
+- March 2024: The tags for Android were approved through :pep:`738`.
 
 
 .. _musl: https://musl.libc.org

source/specifications/pyproject-toml.rst

@@ -252,7 +252,7 @@ The table subkeys of the ``license`` key are deprecated.
 
 - TOML_ type: array of strings
 - Corresponding :ref:`core metadata <core-metadata>` field:
-  :ref:`License-Expression <core-metadata-license-file>`
+  :ref:`License-File <core-metadata-license-file>`
 
 An array specifying paths in the project source tree relative to the project
 root directory (i.e. directory containing :file:`pyproject.toml` or legacy project