From 1fa2817f5fb0e773d3a7ce020a5cd23c66136c9a Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Fri, 26 Jun 2020 11:12:38 -0700 Subject: [PATCH] PEP 621: Try to simplify the motivation section (#1469) --- pep-0621.rst | 52 ++++++++++++++++++++++------------------------------ 1 file changed, 22 insertions(+), 30 deletions(-) diff --git a/pep-0621.rst b/pep-0621.rst index 6890863a9..eb90dbb31 100644 --- a/pep-0621.rst +++ b/pep-0621.rst @@ -20,42 +20,34 @@ Abstract ======== This PEP specifies how to write a project's `core metadata`_ in a -``pyproject.toml`` for packaging-related tools to consume. +``pyproject.toml`` file for packaging-related tools to consume. Motivation ========== -Up until now, all tools in the Python community had their -own unique way for users to specify the `core metadata`_ for their -project. This is unfortunate as the metadata itself is standardized -at a lower level for when build back-ends record this information in -e.g. a wheel file. It means users must learn a specific way to specify -something for whichever build back-end they choose. Unfortunately a -`survey of tools`_ both in the Python community and outside of it -showed that there was very little in the way of consistent agreement -on how to record project metadata. +The key motivators of this PEP are: -This lack of standardization becomes a form of lock-in for build -back-ends. When migration requires learning a new set of terms and a -way to record metadata, it makes transitioning to another tool -cumbersome. That leads to less innovation in the packaging ecosystem -as people are less likely to try out other approaches. +- Encourage users to specify core metadata statically for speed, + ease of specifying, and deterministic consuming +- Provide a tool-agnostic way of specifying the metadata for ease of + learning and transitioning between build back-ends +- Allow for more code sharing between build back-ends for the + "boring parts" of a project's metadata -A single format makes specifying project metadata easier to learn. As -things currently stand, one must find a tutorial for the appropriate -build back-end when it comes to learning how to record metadata. This -leads to duplicated effort in teaching and debugging: when trying to -help users, you must find out which build back-end they are using and -hope you are familiar with that tool. +This PEP does **not** attempt to standardize all possible metadata +required to build a wheel, only the metadata covered by the +`core metadata`_ specification which are very common across projects +and would stand to benefit from being static and consistently +specified. This means build back-ends are still free and able to +innovate around patterns like how to specify the files to include in a +wheel. There is also an included escape hatch for users and build +back-ends to use when they choose to partially opt-out of this PEP +(compared to opting-out of this PEP entirely, which is also possible). -Finally, this PEP makes core metadata for projects statically defined. -By being statically defined, metadata can be read more quickly and -easily than if it were dynamically calculated. Tools which read -and write metadata can do so without worrying about which build -back-end the user specified the metadata for. Statically defined -metadata is also more secure, since it does not require code execution -to gather, and is guaranteed to be deterministic. +This PEP is also not trying to change the underlying `core metadata`_ +in any way. Such considerations should be done in a separate PEP which +may lead to changes or additions to what this PEP specifies. Rationale @@ -66,7 +58,7 @@ The design guidelines the authors of this PEP followed were: - Define as much of the `core metadata`_ as reasonable - Define the metadata statically with an escape hatch for those who want to define it dynamically -- Use familiar names where it made sense, but be willing to use more +- Use familiar names where it makes sense, but be willing to use more modern terminology - Try to be ergonomic within a TOML file instead of mirroring how tools specify metadata at a low-level @@ -94,7 +86,7 @@ Tools MUST specify fields defined by this PEP in a table named defined by this PEP. For tools wishing to store their own settings in ``pyproject.toml``, they may use the ``[tool]`` table as defined in :pep:`518`. The lack of a ``[project]`` table implicitly means the -build tool will dynamically provide all fields. +build back-end will dynamically provide all fields. ``name`` ''''''''