Proof-read through "Example"

Author: brettcannon

peps/pep-0751.rst

@@ -37,7 +37,7 @@ Those tools also vary in what locking scenarios they support. For instance,
 ``pip freeze`` and pip-tools only generate lock files for the current
 environment while PDM, Poetry, and uv can/try to lock for multiple environments
 at once. There's also concerns around the lack of secure defaults in the face of
-supply chain attacks (e.g., always including hashes for files).
+supply chain attacks (e.g., including hashes for files).
 
 The lack of a standard also has some drawbacks. For instance, any tooling that
 wants to work with lock files must choose which format to support, potentially
@@ -46,17 +46,18 @@ same for cloud providers who can do dependency installations on your behalf,
 etc.). It also impacts portability between tools, which causes vendor lock-in.
 By not having compatibility and interoperability it fractures tooling around
 lock files where both users and tools have to choose what lock file format to
-use upfront and making it costly to use/switch to other formats. Rallying
-around a single format removes that cost/barrier.
+use upfront and making it costly to use/switch to other formats (e.g., tooling
+around auditing a lock file). Rallying around a single format removes this
+cost/barrier.
 
 The closest the community has to a standard are pip's `requirements files`_
 which all the aforementioned tools either use directly as their file format or
 export to (i.e. ``requirements.txt``). Unfortunately the format is not a
 standard but is supported by convention. It's also designed very much for pip's
 needs, limiting its flexibility and ease of use (e.g., it's a bespoke file
 format). Lastly, it is not secure by default (e.g., file hash support is
-entirely an opt-in feature, you have to tell pip to not look for external
-dependencies instead of the file encoding such details, etc.).
+entirely an opt-in feature, you have to tell pip to not look for other
+dependencies outside of what's in the requirements file, etc.).
 
 .. note::
 
@@ -67,9 +68,9 @@ dependencies instead of the file encoding such details, etc.).
 Rationale
 =========
 
-The file format is designed to be human-readable. This is so that the contents
-of the file can be audited by a human to make sure no undesired dependencies end
-up being included in the lock file.
+The file format proposed by this PEP is designed to be human-readable. This is
+so that the contents of the file can be audited by a human to make sure no
+undesired dependencies end up being included in the lock file.
 
 The file format is also designed to not require a resolver at install time. This
 greatly simplifies reasoning about what would be installed when consuming a lock
@@ -81,8 +82,8 @@ allows for e.g., clould hosting providers to write their own tool to perform
 installations in their preferred programming language.
 
 The file format should promote good security defaults. As the format is not
-meant to be human-writable, this means providing tools the ability to include
-relevant details to perform installs securely.
+meant to be human-writable, this means having tools provide security-related
+details is reasonable and not a costly burden.
 
 The contents of a lock file should be able to replace the vast majority of uses
 of `requirements files`_ that are used as a lock file (e.g., what
@@ -104,7 +105,7 @@ A lock file MUST be named :file:`pylock.toml` or match the regular expression
 lock files exist. The use of the ``.toml`` file extension is to make syntax
 highlighting in editors easier and to reinforce the fact that the file format is
 meant to be human-readable. The prefix and suffix of a named file MUST be
-lowercase when possible for easy detection and stripping off to find the name,
+lowercase when possible for easy detection and removal,
 e.g.:
 
 .. code-block:: Python
@@ -128,7 +129,7 @@ The format of the file is TOML_.
 Tools SHOULD write their lock files in a consistent way to minmize noise in diff
 output. Keys in tables -- including the top-level table -- SHOULD be recorded in
 a consistent order. As well, tools SHOULD sort arrays in consistent order. Usage
-of inline tables should also be kept consistent.
+of inline tables SHOULD also be kept consistent.
 
 
 ``metadata-version``
@@ -140,7 +141,7 @@ of inline tables should also be kept consistent.
 - Record the file format version that the file adheres to.
 - This PEP specifies the initial version -- and only valid value until future
   updates to the standard change it -- as ``"1.0"``.
-- If an tool supports the major version but not the minor version, a tool
+- If a tool supports the major version but not the minor version, a tool
   SHOULD warn when an unknown key is seen.
 - If an tool doesn't support a major version, it MUST raise an error.
 
@@ -164,7 +165,8 @@ of inline tables should also be kept consistent.
 - **Required?**: no
 - **Inspiration**: PDM_, Poetry_, uv_
 - Specifies the :ref:`packaging:core-metadata-requires-python` for the minimum
-  Python version compatibility for any environment supported by the lock file.
+  Python version compatibile for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
 
 
 ``[[packages]]``
@@ -173,7 +175,7 @@ of inline tables should also be kept consistent.
 - **Type**: array of tables
 - **Required?**: yes
 - **Inspiration**: PDM_, Poetry_, uv_
-- An array containing all packages that _may_ be installed.
+- An array containing all packages that *may* be installed.
 - Packages MAY be listed multiple times with varying data, but all packages to
   be installed MUST narrow down to a single entry at install time.
 
@@ -201,7 +203,8 @@ of inline tables should also be kept consistent.
   :ref:`wheels <packaging:binary-distribution-format>` are specified).
 - The version MUST NOT be included when it cannot be guaranteed to be consistent
   with the code used (i.e. when a
-  :ref:`packaging:source-distribution-format-source-tree` is used).
+  :ref:`source tree <packaging:source-distribution-format-source-tree>` is
+  used).
 
 
 .. Requirements
@@ -212,8 +215,9 @@ of inline tables should also be kept consistent.
 - **Type**: string
 - **Required?**: no
 - **Inspiration**: PDM_
-- The :ref:`packaging:dependency-specifiers-environment-markers` which specify
-  when the package should be installed.
+- The
+  :ref:`environment marker <packaging:dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
 
 
 ``packages.requires-python``
@@ -223,8 +227,7 @@ of inline tables should also be kept consistent.
 - **Required?**: no
 - **Inspiration**: :ref:`packaging:core-metadata-requires-python`
 - Holds the :ref:`packaging:version-specifiers` for Python version compatibility
-  for the package and version.
-- The value MUST match what's provided by the referenced package.
+  for the package.
 
 
 .. Installation
@@ -249,7 +252,8 @@ of inline tables should also be kept consistent.
   ``packaging.archive``, ``packaging.sdist``, and ``packaging.wheels``
 - **Inspiration**: :ref:`packaging:direct-url-data-structure`
 - Record the version control system details for the
-  :ref:`packaging:source-distribution-format-source-tree` it contains.
+  :ref:`source tree <packaging:source-distribution-format-source-tree>` it
+  contains.
 - Tools MAY choose to not support version control systems, both from a locking
   and/or installation perspective.
 - Tools SHOULD provide a way for users to opt out of using version control
@@ -272,7 +276,7 @@ of inline tables should also be kept consistent.
 - **Type**: string
 - **Required?**: if ``path`` is not specified
 - **Inspiration**: :ref:`packaging:direct-url-data-structure-vcs`
-- The URL to the repository.
+- The URL to the source tree.
 
 
 ``packaging.vcs.path``
@@ -281,10 +285,10 @@ of inline tables should also be kept consistent.
 - **Type**: string
 - **Required?**: if ``url`` is not specified
 - **Inspiration**: :ref:`packaging:direct-url-data-structure-vcs`
-- The path to the local directory of the repository.
+- The path to the local directory of the source tree.
 - If a relative path is used it MUST be relative to the location of this file.
-- If the path is relative it MAY use POSIX-style path separators for
-  portability.
+- If the path is relative it MAY use POSIX-style path separators explicitly
+  for portability.
 
 
 ``packaging.vcs.requested-revision``
@@ -294,6 +298,9 @@ of inline tables should also be kept consistent.
 - **Required?**: no
 - **Inspiration**: :ref:`packaging:direct-url-data-structure-vcs`
 - The branch/tag/ref/commit/revision/etc. that the user requested.
+- This is purely informational and to facilitate writing the
+  :ref:`packaging:direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
 
 
 ``packaging.vcs.commit-id``
@@ -304,7 +311,7 @@ of inline tables should also be kept consistent.
 - **Inspiration**: :ref:`packaging:direct-url-data-structure-vcs`
 - The exact commit/revision number that is to be installed.
 - If the VCS supports commit-hash based revision identifiers, such commit-hash
-  MUST be used as the commit id in order to reference an immutable version of
+  MUST be used as the commit ID in order to reference an immutable version of
   the source code.
 
 
@@ -315,8 +322,9 @@ of inline tables should also be kept consistent.
 - **Required?**: no
 - **Inspiration**: :ref:`packaging:direct-url-data-structure-subdirectories`
 - The subdirectory within the
-  :ref:`packaging:source-distribution-format-source-tree` where the project root
-  of the project is (e.g., the location of the ``pyproject.toml`` file).
+  :ref:`source tree <packaging:source-distribution-format-source-tree>` where
+  the project root of the project is (e.g., the location of the
+  ``pyproject.toml`` file).
 - The path MUST be relative to the root of the source tree structure.
 
 
@@ -328,7 +336,8 @@ of inline tables should also be kept consistent.
   ``packaging.archive``, ``packaging.sdist``, and ``packaging.wheels``
 - **Inspiration**: :ref:`packaging:direct-url-data-structure-local-directory`
 - Record the local directory details for the
-  :ref:`packaging:source-distribution-format-source-tree` it contains.
+  :ref:`source tree <packaging:source-distribution-format-source-tree>` it
+  contains.
 - Tools MAY choose to not support local directories, both from a locking
   and/or installation perspective.
 - Tools SHOULD provide a way for users to opt out of using local directories.
@@ -580,7 +589,7 @@ Example
   requires-python = ">=3.7"
   index = "https://pypi.org/simple/"
   wheels = [
-      {name = "attrs-23.2.0-py3-none-any.whl", upload-time = 2023-12-31T06:30:30.772444Z, url = "https://files.pythonhosted.org/packages/e0/44/827b2a91a5816512fcaf3cc4ebc465ccd5d598c45cefa6703fcf4a79018f/attrs-23.2.0-py3-none-any.whl", size = 60752, hashes = {"sha256" = "99b87a485a5820b23b879f04c2305b44b951b502fd64be915879d77a7e8fc6f1"} }
+      {name = "attrs-23.2.0-py3-none-any.whl", upload-time = 2023-12-31T06:30:30.772444Z, url = "https://files.pythonhosted.org/packages/e0/44/827b2a91a5816512fcaf3cc4ebc465ccd5d598c45cefa6703fcf4a79018f/attrs-23.2.0-py3-none-any.whl", size = 60752, hashes = {sha256 = "99b87a485a5820b23b879f04c2305b44b951b502fd64be915879d77a7e8fc6f1"} }
   ]
 
   [[packages]]
@@ -589,7 +598,7 @@ Example
   requires-python = ">=3.8"
   index = "https://pypi.org/simple/"
   wheels = [
-      {name = "cattrs-23.2.3-py3-none-any.whl", upload-time = 2023-11-30T22:19:19.163763Z, url = "https://files.pythonhosted.org/packages/b3/0d/cd4a4071c7f38385dc5ba91286723b4d1090b87815db48216212c6c6c30e/cattrs-23.2.3-py3-none-any.whl", size = 57474, hashes = {"sha256" = "0341994d94971052e9ee70662542699a3162ea1e0c62f7ce1b4a57f563685108"} }
+      {name = "cattrs-23.2.3-py3-none-any.whl", upload-time = 2023-11-30T22:19:19.163763Z, url = "https://files.pythonhosted.org/packages/b3/0d/cd4a4071c7f38385dc5ba91286723b4d1090b87815db48216212c6c6c30e/cattrs-23.2.3-py3-none-any.whl", size = 57474, hashes = {sha256 = "0341994d94971052e9ee70662542699a3162ea1e0c62f7ce1b4a57f563685108"} }
   ]
 
   [[packages]]
@@ -598,16 +607,16 @@ Example
   requires-python = ">=3.9"
   index = "https://pypi.org/simple/"
   files = [
-      {name = "numpy-2.0.1-cp312-cp312-macosx_10_9_x86_64.whl", upload-time = 2024-07-21T13:37:15.810939Z, url = "https://files.pythonhosted.org/packages/64/1c/401489a7e92c30db413362756c313b9353fb47565015986c55582593e2ae/numpy-2.0.1-cp312-cp312-macosx_10_9_x86_64.whl", size = 20965374, hashes = {"sha256" = "6bf4e6f4a2a2e26655717a1983ef6324f2664d7011f6ef7482e8c0b3d51e82ac"} },
-      {name = "numpy-2.0.1-cp312-cp312-macosx_11_0_arm64.whl", "upload-time" = 2024-07-21T13:37:36.460324Z, "url" = "https://files.pythonhosted.org/packages/08/61/460fb524bb2d1a8bd4bbcb33d9b0971f9837fdedcfda8478d4c8f5cfd7ee/numpy-2.0.1-cp312-cp312-macosx_11_0_arm64.whl", "size" = 13102536, hashes = {"sha256" = "7d6fddc5fe258d3328cd8e3d7d3e02234c5d70e01ebe377a6ab92adb14039cb4"} },
-      {name = "numpy-2.0.1-cp312-cp312-macosx_14_0_arm64.whl", "upload-time" = 2024-07-21T13:37:46.601144Z, "url" = "https://files.pythonhosted.org/packages/c2/da/3d8debb409bc97045b559f408d2b8cefa6a077a73df14dbf4d8780d976b1/numpy-2.0.1-cp312-cp312-macosx_14_0_arm64.whl", "size" = 5037809, hashes = {"sha256" = "5daab361be6ddeb299a918a7c0864fa8618af66019138263247af405018b04e1"} },
-      {name = "numpy-2.0.1-cp312-cp312-macosx_14_0_x86_64.whl", "upload-time" = 2024-07-21T13:37:58.784393Z, "url" = "https://files.pythonhosted.org/packages/6d/59/85160bf5f4af6264a7c5149ab07be9c8db2b0eb064794f8a7bf6d/numpy-2.0.1-cp312-cp312-macosx_14_0_x86_64.whl", "size" = 6631813, hashes = {"sha256" = "ea2326a4dca88e4a274ba3a4405eb6c6467d3ffbd8c7d38632502eaae3820587"} },
-      {name = "numpy-2.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", "upload-time" = 2024-07-21T13:38:19.714559Z, "url" = "https://files.pythonhosted.org/packages/5e/e3/944b77e2742fece7da8dfba6f7ef7dccdd163d1a613f7027f4d5b/numpy-2.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", "size" = 13623742, hashes = {"sha256" = "529af13c5f4b7a932fb0e1911d3a75da204eff023ee5e0e79c1751564221a5c8"} },
-      {name = "numpy-2.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", "upload-time" = 2024-07-21T13:38:48.972569Z, "url" = "https://files.pythonhosted.org/packages/2c/f3/61eee37decb58e7cb29940f19a1464b8608f2cab8a8616aba75fd/numpy-2.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", "size" = 19242336, hashes = {"sha256" = "6790654cb13eab303d8402354fabd47472b24635700f631f041bd0b65e37298a"} },
-      {name = "numpy-2.0.1-cp312-cp312-musllinux_1_1_x86_64.whl", "upload-time" = 2024-07-21T13:39:19.213811Z, "url" = "https://files.pythonhosted.org/packages/77/b5/c74cc436114c1de5912cdb475145245f6e645a6a1a29b5d08c774/numpy-2.0.1-cp312-cp312-musllinux_1_1_x86_64.whl", "size" = 19637264, hashes = {"sha256" = "cbab9fc9c391700e3e1287666dfd82d8666d10e69a6c4a09ab97574c0b7ee0a7"} },
-      {name = "numpy-2.0.1-cp312-cp312-musllinux_1_2_aarch64.whl", "upload-time" = 2024-07-21T13:39:41.812321Z, "url" = "https://files.pythonhosted.org/packages/da/89/c8856e12e0b3f6af371ccb90d604600923b08050c58f0cd26eac9/numpy-2.0.1-cp312-cp312-musllinux_1_2_aarch64.whl", "size" = 14108911, hashes = {"sha256" = "99d0d92a5e3613c33a5f01db206a33f8fdf3d71f2912b0de1739894668b7a93b"} },
-      {name = "numpy-2.0.1-cp312-cp312-win32.whl", "upload-time" = 2024-07-21T13:39:52.932102Z, "url" = "https://files.pythonhosted.org/packages/15/96/310c6f6d146518479b0a6ee6eb92a537954ec3b1acfa2894d1347/numpy-2.0.1-cp312-cp312-win32.whl", "size" = 6171379, hashes = {"sha256" = "173a00b9995f73b79eb0191129f2455f1e34c203f559dd118636858cc452a1bf"} },
-      {name = "numpy-2.0.1-cp312-cp312-win_amd64.whl", "upload-time" = 2024-07-21T13:40:17.532627Z, "url" = "https://files.pythonhosted.org/packages/b5/59/f6ad378ad85ed9c2785f271b39c3e5b6412c66e810d2c60934c9f/numpy-2.0.1-cp312-cp312-win_amd64.whl", "size" = 16255757, hashes = {"sha256" = "bb2124fdc6e62baae159ebcfa368708867eb56806804d005860b6007388df171"} },
+      {name = "numpy-2.0.1-cp312-cp312-macosx_10_9_x86_64.whl", upload-time = 2024-07-21T13:37:15.810939Z, url = "https://files.pythonhosted.org/packages/64/1c/401489a7e92c30db413362756c313b9353fb47565015986c55582593e2ae/numpy-2.0.1-cp312-cp312-macosx_10_9_x86_64.whl", size = 20965374, hashes = {sha256 = "6bf4e6f4a2a2e26655717a1983ef6324f2664d7011f6ef7482e8c0b3d51e82ac"} },
+      {name = "numpy-2.0.1-cp312-cp312-macosx_11_0_arm64.whl", upload-time = 2024-07-21T13:37:36.460324Z, url = "https://files.pythonhosted.org/packages/08/61/460fb524bb2d1a8bd4bbcb33d9b0971f9837fdedcfda8478d4c8f5cfd7ee/numpy-2.0.1-cp312-cp312-macosx_11_0_arm64.whl", size = 13102536, hashes = {sha256 = "7d6fddc5fe258d3328cd8e3d7d3e02234c5d70e01ebe377a6ab92adb14039cb4"} },
+      {name = "numpy-2.0.1-cp312-cp312-macosx_14_0_arm64.whl", upload-time = 2024-07-21T13:37:46.601144Z, url = "https://files.pythonhosted.org/packages/c2/da/3d8debb409bc97045b559f408d2b8cefa6a077a73df14dbf4d8780d976b1/numpy-2.0.1-cp312-cp312-macosx_14_0_arm64.whl", size = 5037809, hashes = {sha256 = "5daab361be6ddeb299a918a7c0864fa8618af66019138263247af405018b04e1"} },
+      {name = "numpy-2.0.1-cp312-cp312-macosx_14_0_x86_64.whl", upload-time = 2024-07-21T13:37:58.784393Z, url = "https://files.pythonhosted.org/packages/6d/59/85160bf5f4af6264a7c5149ab07be9c8db2b0eb064794f8a7bf6d/numpy-2.0.1-cp312-cp312-macosx_14_0_x86_64.whl", size = 6631813, hashes = {sha256 = "ea2326a4dca88e4a274ba3a4405eb6c6467d3ffbd8c7d38632502eaae3820587"} },
+      {name = "numpy-2.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", upload-time = 2024-07-21T13:38:19.714559Z, url = "https://files.pythonhosted.org/packages/5e/e3/944b77e2742fece7da8dfba6f7ef7dccdd163d1a613f7027f4d5b/numpy-2.0.1-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", size = 13623742, hashes = {sha256 = "529af13c5f4b7a932fb0e1911d3a75da204eff023ee5e0e79c1751564221a5c8"} },
+      {name = "numpy-2.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", upload-time = 2024-07-21T13:38:48.972569Z, url = "https://files.pythonhosted.org/packages/2c/f3/61eee37decb58e7cb29940f19a1464b8608f2cab8a8616aba75fd/numpy-2.0.1-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", size = 19242336, hashes = {sha256 = "6790654cb13eab303d8402354fabd47472b24635700f631f041bd0b65e37298a"} },
+      {name = "numpy-2.0.1-cp312-cp312-musllinux_1_1_x86_64.whl", upload-time = 2024-07-21T13:39:19.213811Z, url = "https://files.pythonhosted.org/packages/77/b5/c74cc436114c1de5912cdb475145245f6e645a6a1a29b5d08c774/numpy-2.0.1-cp312-cp312-musllinux_1_1_x86_64.whl", size = 19637264, hashes = {sha256 = "cbab9fc9c391700e3e1287666dfd82d8666d10e69a6c4a09ab97574c0b7ee0a7"} },
+      {name = "numpy-2.0.1-cp312-cp312-musllinux_1_2_aarch64.whl", upload-time = 2024-07-21T13:39:41.812321Z, url = "https://files.pythonhosted.org/packages/da/89/c8856e12e0b3f6af371ccb90d604600923b08050c58f0cd26eac9/numpy-2.0.1-cp312-cp312-musllinux_1_2_aarch64.whl", size = 14108911, hashes = {sha256 = "99d0d92a5e3613c33a5f01db206a33f8fdf3d71f2912b0de1739894668b7a93b"} },
+      {name = "numpy-2.0.1-cp312-cp312-win32.whl", upload-time = 2024-07-21T13:39:52.932102Z, url = "https://files.pythonhosted.org/packages/15/96/310c6f6d146518479b0a6ee6eb92a537954ec3b1acfa2894d1347/numpy-2.0.1-cp312-cp312-win32.whl", size = 6171379, hashes = {sha256 = "173a00b9995f73b79eb0191129f2455f1e34c203f559dd118636858cc452a1bf"} },
+      {name = "numpy-2.0.1-cp312-cp312-win_amd64.whl", upload-time = 2024-07-21T13:40:17.532627Z, url = "https://files.pythonhosted.org/packages/b5/59/f6ad378ad85ed9c2785f271b39c3e5b6412c66e810d2c60934c9f/numpy-2.0.1-cp312-cp312-win_amd64.whl", size = 16255757, hashes = {sha256 = "bb2124fdc6e62baae159ebcfa368708867eb56806804d005860b6007388df171"} },
   ]