Repository: pypa/packaging.python.org
Pull request #1848: Add PEP 751
Author: login: brettcannon
Created: 2025-04-14T23:28:49Z | Merged: 2025-05-02T23:52:40Z



<!-- readthedocs-preview python-packaging-user-guide start -->
----
📚 Documentation preview 📚: https://python-packaging-user-guide--1848.org.readthedocs.build/en/1848/

<!-- readthedocs-preview python-packaging-user-guide end -->


Diff:
diff --git a/source/conf.py b/source/conf.py
index bda71103a..d41db4957 100644
--- a/source/conf.py
+++ b/source/conf.py
@@ -145,6 +145,7 @@
     "https://stackoverflow.com/*",
     "https://pyscaffold.org/*",
     "https://anaconda.org",
+    "https://www.cisa.gov/sbom",
 ]
 linkcheck_retries = 5
 # Ignore anchors for common targets when we know they likely won't be found
diff --git a/source/specifications/dependency-specifiers.rst b/source/specifications/dependency-specifiers.rst
index 06897da27..e8e3229ff 100644
--- a/source/specifications/dependency-specifiers.rst
+++ b/source/specifications/dependency-specifiers.rst
@@ -87,7 +87,7 @@ environments::
                      'platform_system' | 'platform_version' |
                      'platform_machine' | 'platform_python_implementation' |
                      'implementation_name' | 'implementation_version' |
-                     'extra' # ONLY when defined by a containing layer
+                     'extra' | 'extras' | 'dependency_groups' # ONLY when defined by a containing layer
                      )
     marker_var    = wsp* (env_var | python_str)
     marker_expr   = marker_var marker_op marker_var
@@ -196,15 +196,16 @@ safely evaluate it without running arbitrary code that could become a security
 vulnerability. Markers were first standardised in :pep:`345`. This document
 fixes some issues that were observed in the design described in :pep:`426`.
 
-Comparisons in marker expressions are typed by the comparison operator.  The
-<marker_op> operators that are not in <version_cmp> perform the same as they
-do for strings in Python. The <version_cmp> operators use the version comparison
-rules of the :ref:`Version specifier specification <version-specifiers>`
-when those are defined (that is when both sides have a valid
-version specifier). If there is no defined behaviour of this specification
-and the operator exists in Python, then the operator falls back to
-the Python behaviour. Otherwise an error should be raised. e.g. the following
-will result in  errors::
+Comparisons in marker expressions are typed by the comparison operator and the
+type of the marker value. The <marker_op> operators that are not in
+<version_cmp> perform the same as they do for strings or sets in Python based on
+whether the marker value is a string or set itself. The <version_cmp> operators
+use the version comparison rules of the
+:ref:`Version specifier specification <version-specifiers>` when those are
+defined (that is when both sides have a valid version specifier). If there is no
+defined behaviour of this specification and the operator exists in Python, then
+the operator falls back to the Python behaviour for the types involved.
+Otherwise an error should be raised. e.g. the following will result in errors::
 
     "dog" ~= "fred"
     python_version ~= "surprise"
@@ -235,52 +236,80 @@ no current specification for this. Regardless, outside of a context where this
 special handling is taking place, the "extra" variable should result in an
 error like all other unknown variables.
 
+The "extras" and "dependency_groups" variables are also special. They are used
+to specify any requested extras or dependency groups when installing from a lock
+file. Outside of the context of lock files, these two variables should result in
+an error like all other unknown variables.
+
 .. list-table::
    :header-rows: 1
 
    * - Marker
      - Python equivalent
+     - Type
      - Sample values
    * - ``os_name``
      - :py:data:`os.name`
+     - String
      - ``posix``, ``java``
    * - ``sys_platform``
      - :py:data:`sys.platform`
+     - String
      - ``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that "linux"
        is from Python3 and "linux2" from Python2)
    * - ``platform_machine``
      - :py:func:`platform.machine()`
+     - String
      - ``x86_64``
    * - ``platform_python_implementation``
      - :py:func:`platform.python_implementation()`
+     - String
      - ``CPython``, ``Jython``
    * - ``platform_release``
      - :py:func:`platform.release()`
+     - String
      - ``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``
    * - ``platform_system``
      - :py:func:`platform.system()`
+     - String
      - ``Linux``, ``Windows``, ``Java``
    * - ``platform_version``
      - :py:func:`platform.version()`
+     - String
      - ``#1 SMP Fri Apr 25 13:07:35 EDT 2014``
        ``Java HotSpot(TM) 64-Bit Server VM, 25.51-b03, Oracle Corporation``
        ``Darwin Kernel Version 14.5.0: Wed Jul 29 02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``
    * - ``python_version``
      - ``'.'.join(platform.python_version_tuple()[:2])``
+     - :ref:`Version <version-specifiers>`
      - ``3.4``, ``2.7``
    * - ``python_full_version``
      - :py:func:`platform.python_version()`
+     - :ref:`Version <version-specifiers>`
      - ``3.4.0``, ``3.5.0b1``
    * - ``implementation_name``
      - :py:data:`sys.implementation.name <sys.implementation>`
+     - String
      - ``cpython``
    * - ``implementation_version``
      - see definition below
+     - :ref:`Version <version-specifiers>`
      - ``3.4.0``, ``3.5.0b1``
    * - ``extra``
      - An error except when defined by the context interpreting the
        specification.
-     - ``test``
+     - String
+     - ``toml``
+   * - ``extras``
+     - An error except when defined by the context interpreting the
+       specification.
+     - Set of strings
+     - ``{"toml"}``
+   * - ``dependency_groups``
+     - An error except when defined by the context interpreting the
+       specification.
+     - Set of strings
+     - ``{"test"}``
 
 The ``implementation_version`` marker variable is derived from
 :py:data:`sys.implementation.version <sys.implementation>`:
@@ -330,7 +359,7 @@ The complete parsley grammar::
                      'platform_system' | 'platform_version' |
                      'platform_machine' | 'platform_python_implementation' |
                      'implementation_name' | 'implementation_version' |
-                     'extra' # ONLY when defined by a containing layer
+                     'extra' | 'extras' | 'dependency_groups' # ONLY when defined by a containing layer
                      ):varname -> lookup(varname)
     marker_var    = wsp* (env_var | python_str)
     marker_expr   = marker_var:l marker_op:o marker_var:r -> (o, l, r)
@@ -495,6 +524,8 @@ History
 - June 2024: The definition of ``version_many`` was changed to allow trailing
   commas, matching with the behavior of the Python implementation that has been
   in use since late 2022.
+- April 2025: Added ``extras`` and ``dependency_groups`` for
+  :ref:`lock-file-spec` as approved through :pep:`751`.
 
 
 References
diff --git a/source/specifications/index.rst b/source/specifications/index.rst
index c69605927..68d95ab98 100644
--- a/source/specifications/index.rst
+++ b/source/specifications/index.rst
@@ -16,3 +16,4 @@ and for proposing new ones, is documented on
    section-distribution-formats
    section-package-indices
    section-python-description-formats
+   section-reproducible-environments
diff --git a/source/specifications/pylock-toml.rst b/source/specifications/pylock-toml.rst
new file mode 100644
index 000000000..d21294cf9
--- /dev/null
+++ b/source/specifications/pylock-toml.rst
@@ -0,0 +1,842 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use :file:`pylock.toml` with a dependency group with the name of the service
+3. The default install of :file:`pylock.toml`
+
+E.g. a cloud host service named "spam" would first look for
+:file:`pylock.spam.toml` to install from, and if that file didn't exist then install
+from :file:`pylock.toml` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single :file:`pyproject.toml`, for instance,
+would place the :file:`pylock.toml` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the :file:`pylock.toml`
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this specification has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+'''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+'''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+'''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-directory-path:
+
+``packages.directory.path``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+.. _pylock-packages-directory-editable:
+
+``packages.directory.editable``
+'''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+.. _pylock-packages-directory-subdirectory:
+
+``packages.directory.subdirectory``
+'''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-archive:
+
+``[packages.archive]``
+----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-archive-url:
+
+``packages.archive.url``
+''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-url`.
+
+
+.. _pylock-packages-archive-path:
+
+``packages.archive.path``
+'''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-path`.
+
+
+.. _pylock-packages-archive-size:
+
+``packages.archive.size``
+'''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+.. _pylock-packages-archive-upload-time:
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+.. _pylock-packages-archive-hashes:
+
+``[packages.archive.hashes]``
+'''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+.. _pylock-packages-archive-subdirectory:
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-index:
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+.. _pylock-packages-sdist:
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+.. _pylock-packages-sdist-name:
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of
+  :ref:`pylock-packages-sdist-path`/ :ref:`pylock-packages-sdist-url` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+.. _pylock-packages-sdist-upload-time:
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-upload-time`.
+
+
+.. _pylock-packages-sdist-url:
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-url`.
+
+
+.. _pylock-packages-sdist-path:
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-path`.
+
+
+.. _pylock-packages-sdist-size:
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-size`.
+
+
+.. _pylock-packages-sdist-hashes:
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-hashes`.
+
+
+
+.. _pylock-packages-wheels:
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+.. _pylock-packages-wheels-name:
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of
+  :ref:`pylock-packages-wheels-path`/ :ref:`pylock-packages-wheels-url` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`binary-distribution-format` file.
+
+
+.. _pylock-packages-wheels-upload-time:
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-upload-time`.
+
+
+.. _pylock-packages-wheels-url:
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-url`.
+
+
+.. _pylock-packages-wheels-path:
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-path`.
+
+
+.. _pylock-packages-wheels-size:
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-size`.
+
+
+.. _pylock-packages-wheels-hashes:
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-hashes`.
+
+
+.. _pylock-packages-attestation-identities:
+
+``[[packages.attestation-identities]]``
+---------------------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: :ref:`  provenance-object`
+- A recording of the attestations for **any** file recorded for this package.
+- If available, tools SHOULD include the attestation identities found.
+- Publisher-specific keys are to be included in the table as-is
+  (i.e. top-level), following the spec at
+  :ref:`  index-hosted-attestations`.
+
+
+.. _pylock-packages-attestation-identities-kind:
+
+``packages.attestation-identities.kind``
+''''''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`  provenance-object`
+- The unique identity of the Trusted Publisher.
+
+
+.. _pylock-packages-tool:
+
+``[packages.tool]``
+-------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- Similar usage as that of the :ref:`pylock-tool` table from the
+  :ref:`  pyproject-toml-spec`, but at the package version level instead
+  of at the lock file level (which is also available via :ref:`pylock-tool`).
+- Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
+  installation).
+
+
+.. _pylock-tool:
+
+``[tool]``
+==========
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`pyproject-tool-table`
+- See :ref:`pylock-packages-tool`.
+
+
+-------
+Example
+-------
+
+.. literalinclude:: pylock-toml/pylock.example.toml
+
+
+------------
+Installation
+------------
+
+The following outlines the steps to be taken to install from a lock file
+(while the requirements are prescriptive, the general steps and order are
+a suggestion):
+
+#. Gather the extras and dependency groups to install and set ``extras`` and
+   ``dependency_groups`` for marker evaluation, respectively.
+
+   #. ``extras`` SHOULD be set to the empty set by default.
+   #. ``dependency_groups`` SHOULD be the set created from
+      :ref:`pylock-default-groups` by default.
+
+#. Check if the metadata version specified by :ref:`pylock-lock-version` is
+   supported; an error or warning MUST be raised as appropriate.
+#. If :ref:`pylock-requires-python` is specified, check that the environment
+   being installed for meets the requirement; an error MUST be raised if it is
+   not met.
+#. If :ref:`pylock-environments` is specified, check that at least one of the
+   environment marker expressions is satisfied; an error MUST be raised if no
+   expression is satisfied.
+#. For each package listed in :ref:`pylock-packages`:
+
+   #. If :ref:`pylock-packages-marker` is specified, check if it is satisfied;
+      if it isn't, skip to the next package.
+   #. If :ref:`pylock-packages-requires-python` is specified, check if it is
+      satisfied; an error MUST be raised if it isn't.
+   #. Check that no other conflicting instance of the package has been slated to
+      be installed; an error about the ambiguity MUST be raised otherwise.
+   #. Check that the source of the package is specified appropriately (i.e.
+      there are no conflicting sources in the package entry);
+      an error MUST be raised if any issues are found.
+   #. Add the package to the set of packages to install.
+
+#. For each package to be installed:
+
+   - If :ref:`pylock-packages-vcs` is set:
+
+     #. Clone the repository to the commit ID specified in
+        :ref:`pylock-packages-vcs-commit-id`.
+     #. :ref:`Build <source-distribution-format-source-tree>` the package,
+        respecting :ref:`pylock-packages-vcs-subdirectory`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if :ref:`pylock-packages-directory` is set:
+
+     #. :ref:`Build <source-distribution-format-source-tree>` the package,
+        respecting :ref:`pylock-packages-directory-subdirectory`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if :ref:`pylock-packages-archive` is set:
+
+     #. Get the file.
+     #. Validate using :ref:`pylock-packages-archive-size` and
+        :ref:`pylock-packages-archive-hashes`.
+     #. :ref:`Build <source-distribution-format-source-tree>` the package,
+        respecting :ref:`pylock-packages-archive-subdirectory`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if there are entries for :ref:`pylock-packages-wheels`:
+
+     #. Look for the appropriate wheel file based on
+        :ref:`pylock-packages-wheels-name`; if one is not found then move on to
+        :ref:`pylock-packages-sdist` or an error MUST be raised about a
+        lack of source for the project.
+     #. Get the file:
+
+        - If :ref:`pylock-packages-wheels-path` is set, use it.
+        - Else if :ref:`pylock-packages-wheels-url` is set, try to use it;
+          optionally tools MAY use :ref:`pylock-packages-index` or some
+          tool-specific mechanism to download the selected wheel file (tools
+          MUST NOT try to change what wheel file to download based on what's
+          available; what file to install should be determined in an offline
+          fashion for reproducibility).
+
+     #. Validate using :ref:`pylock-packages-wheels-size` and
+        :ref:`pylock-packages-wheels-hashes`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if no :ref:`pylock-packages-wheels` file is found or
+     :ref:`pylock-packages-sdist` is solely set:
+
+     #. Get the file.
+
+        - If :ref:`pylock-packages-sdist-path` is set, use it.
+        - Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools
+          MAY use :ref:`pylock-packages-index` or some tool-specific mechanism
+          to download the file.
+
+     #. Validate using :ref:`pylock-packages-sdist-size` and
+        :ref:`pylock-packages-sdist-hashes`.
+     #. :ref:`Build <source-distribution-format-sdist>` the package.
+     #. :ref:`Install <binary-distribution-format>`.
+
+
+-------
+History
+-------
+
+- April 2025: Initial version, approved via :pep:`751`.
+
+
+.. _Content-Length: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Length
+.. _Dependabot: https://docs.github.com/en/code-security/dependabot
+.. _HEAD: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD
+.. _PDM: https://pypi.org/project/pdm/
+.. _pip-tools: https://pypi.org/project/pip-tools/
+.. _Poetry: https://pypi.org/project/poetry/
+.. _requirements file:
+.. _requirements files: https://pip.pypa.io/en/stable/reference/requirements-file-format/
+.. _software bill of materials: https://www.cisa.gov/sbom
+.. _TOML: https://toml.io/
+.. _uv: https://pypi.org/project/uv/
+.. _URL: https://url.spec.whatwg.org/
diff --git a/source/specifications/pylock-toml/pylock.example.toml b/source/specifications/pylock-toml/pylock.example.toml
new file mode 100644
index 000000000..45e8731b2
--- /dev/null
+++ b/source/specifications/pylock-toml/pylock.example.toml
@@ -0,0 +1,60 @@
+lock-version = '1.0'
+environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
+requires-python = '== 3.12'
+created-by = 'mousebender'
+
+[[packages]]
+name = 'attrs'
+version = '25.1.0'
+requires-python = '>= 3.8'
+
+    [[packages.wheels]]
+    name = 'attrs-25.1.0-py3-none-any.whl'
+    upload-time = 2025-01-25T11:30:10.164985+00:00
+    url = 'https://files.pythonhosted.org/packages/fc/30/d4986a882011f9df997a55e6becd864812ccfcd821d64aac8570ee39f719/attrs-25.1.0-py3-none-any.whl'
+    size = 63152
+    hashes = {sha256 = 'c75a69e28a550a7e93789579c22aa26b0f5b83b75dc4e08fe092980051e1090a'}
+
+    [[packages.attestation-identities]]
+    environment = 'release-pypi'
+    kind = 'GitHub'
+    repository = 'python-attrs/attrs'
+    workflow = 'pypi-package.yml'
+
+[[packages]]
+name = 'cattrs'
+version = '24.1.2'
+requires-python = '>= 3.8'
+dependencies = [
+    {name = 'attrs'},
+]
+
+    [[packages.wheels]]
+    name = 'cattrs-24.1.2-py3-none-any.whl'
+    upload-time = 2024-09-22T14:58:34.812643+00:00
+    url = 'https://files.pythonhosted.org/packages/c8/d5/867e75361fc45f6de75fe277dd085627a9db5ebb511a87f27dc1396b5351/cattrs-24.1.2-py3-none-any.whl'
+    size = 66446
+    hashes = {sha256 = '67c7495b760168d931a10233f979b28dc04daf853b30752246f4f8471c6d68d0'}
+
+[[packages]]
+name = 'numpy'
+version = '2.2.3'
+requires-python = '>= 3.10'
+
+    [[packages.wheels]]
+    name = 'numpy-2.2.3-cp312-cp312-win_amd64.whl'
+    upload-time = 2025-02-13T16:51:21.821880+00:00
+    url = 'https://files.pythonhosted.org/packages/42/6e/55580a538116d16ae7c9aa17d4edd56e83f42126cb1dfe7a684da7925d2c/numpy-2.2.3-cp312-cp312-win_amd64.whl'
+    size = 12626357
+    hashes = {sha256 = '83807d445817326b4bcdaaaf8e8e9f1753da04341eceec705c001ff342002e5d'}
+
+    [[packages.wheels]]
+    name = 'numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl'
+    upload-time = 2025-02-13T16:50:00.079662+00:00
+    url = 'https://files.pythonhosted.org/packages/39/04/78d2e7402fb479d893953fb78fa7045f7deb635ec095b6b4f0260223091a/numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl'
+    size = 16116679
+    hashes = {sha256 = '3b787adbf04b0db1967798dba8da1af07e387908ed1553a0d6e74c084d1ceafe'}
+
+[tool.mousebender]
+command = ['.', 'lock', '--platform', 'cpython3.12-windows-x64', '--platform', 'cpython3.12-manylinux2014-x64', 'cattrs', 'numpy']
+run-on = 2025-03-06T12:28:57.760769
diff --git a/source/specifications/section-reproducible-environments.rst b/source/specifications/section-reproducible-environments.rst
new file mode 100644
index 000000000..1f83f3673
--- /dev/null
+++ b/source/specifications/section-reproducible-environments.rst
@@ -0,0 +1,8 @@
+=========================
+Reproducible Environments
+=========================
+
+.. toctree::
+   :titlesonly:
+
+   pylock-toml


Reviews:
user: login: FFY00
body: Looks good, I just have a couple comments.
state: APPROVED
author_association: MEMBER
submitted_at: 2025-04-15T14:56:18Z
user: login: FFY00
body: Here are the reference changes.
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-15T15:31:25Z
user: login: FFY00
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-15T15:37:56Z
user: login: brettcannon
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-15T20:39:30Z
user: login: webknjaz
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-16T12:41:59Z
user: login: webknjaz
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-16T13:30:10Z
user: login: webknjaz
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-16T13:30:56Z
user: login: webknjaz
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-16T13:32:53Z
user: login: brettcannon
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-04-16T17:57:25Z
user: login: willingc
body: Thanks @brettcannon. Looking good.
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-24T00:01:40Z
user: login: webknjaz
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-02T17:30:51Z
user: login: brettcannon
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-02T21:09:36Z
user: login: brettcannon
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-02T23:12:08Z
user: login: webknjaz
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-02T23:42:50Z
user: login: webknjaz
state: COMMENTED
author_association: MEMBER
submitted_at: 2025-05-02T23:46:38Z
user: login: webknjaz
body: @brettcannon thanks!

P.S. Plz prefer rebasing in this repo in the future since merge queues are set up to use natural merge and merging in the opposite direction causes "foxtrots".
state: APPROVED
author_association: MEMBER
submitted_at: 2025-05-02T23:48:50Z

Review comments:
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+``[[packages.attestation-identities]]``
+---------------------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: :ref:`  provenance-object`
+- A recording of the attestations for **any** file recorded for this package.
+- If available, tools SHOULD include the attestation identities found.
+- Publisher-specific keys are to be included in the table as-is
+  (i.e. top-level), following the spec at
+  :ref:`  index-hosted-attestations`.
+
+
+``packages.attestation-identities.kind``
+''''''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`  provenance-object`
+- The unique identity of the Trusted Publisher.
+
+
+``[packages.tool]``
+-------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- Similar usage as that of the ``[tool]`` table from the
+  :ref:`  pyproject-toml-spec`, but at the package version level instead
+  of at the lock file level (which is also available via ``[tool]``).
+- Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
+  installation).
+
+
+``[tool]``
+==========
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- See ``packages.tool``.
+
+
+-------
+Example
+-------
+
+.. code-block:: TOML
+
+  lock-version = '1.0'
+  environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
+  requires-python = '==3.12'
+  created-by = 'mousebender'
+
+  [[packages]]
+  name = 'attrs'
+  version = '25.1.0'
+  requires-python = '>=3.8'
+  wheels = [
+    {name = 'attrs-25.1.0-py3-none-any.whl', upload-time = 2025-01-25T11:30:10.164985+00:00, url = 'https://files.pythonhosted.org/packages/fc/30/d4986a882011f9df997a55e6becd864812ccfcd821d64aac8570ee39f719/attrs-25.1.0-py3-none-any.whl', size = 63152, hashes = {sha256 = 'c75a69e28a550a7e93789579c22aa26b0f5b83b75dc4e08fe092980051e1090a'}},
+  ]
+  [[packages.attestation-identities]]
+  environment = 'release-pypi'
+  kind = 'GitHub'
+  repository = 'python-attrs/attrs'
+  workflow = 'pypi-package.yml'
+
+  [[packages]]
+  name = 'cattrs'
+  version = '24.1.2'
+  requires-python = '>=3.8'
+  dependencies = [
+      {name = 'attrs'},
+  ]
+  wheels = [
+    {name = 'cattrs-24.1.2-py3-none-any.whl', upload-time = 2024-09-22T14:58:34.812643+00:00, url = 'https://files.pythonhosted.org/packages/c8/d5/867e75361fc45f6de75fe277dd085627a9db5ebb511a87f27dc1396b5351/cattrs-24.1.2-py3-none-any.whl', size = 66446, hashes = {sha256 = '67c7495b760168d931a10233f979b28dc04daf853b30752246f4f8471c6d68d0'}},
+  ]
+
+  [[packages]]
+  name = 'numpy'
+  version = '2.2.3'
+  requires-python = '>=3.10'
+  wheels = [
+    {name = 'numpy-2.2.3-cp312-cp312-win_amd64.whl', upload-time = 2025-02-13T16:51:21.821880+00:00, url = 'https://files.pythonhosted.org/packages/42/6e/55580a538116d16ae7c9aa17d4edd56e83f42126cb1dfe7a684da7925d2c/numpy-2.2.3-cp312-cp312-win_amd64.whl', size = 12626357, hashes = {sha256 = '83807d445817326b4bcdaaaf8e8e9f1753da04341eceec705c001ff342002e5d'}},
+    {name = 'numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', upload-time = 2025-02-13T16:50:00.079662+00:00, url = 'https://files.pythonhosted.org/packages/39/04/78d2e7402fb479d893953fb78fa7045f7deb635ec095b6b4f0260223091a/numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', size = 16116679, hashes = {sha256 = '3b787adbf04b0db1967798dba8da1af07e387908ed1553a0d6e74c084d1ceafe'}},
+  ]
+
+  [tool.mousebender]
+  command = ['.', 'lock', '--platform', 'cpython3.12-windows-x64', '--platform', 'cpython3.12-manylinux2014-x64', 'cattrs', 'numpy']
+  run-on = 2025-03-06T12:28:57.760769
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: nitpick: IMO it becomes easier to read if you expand the `wheels` array. If there's a concern that it might not be as intuitive to folks not super familiarized with the TOML spec, the example already does this for `attestation-identities`, so I think we should probably either reformat `attestation-identities` or `wheels`.

```suggestion
  lock-version = '1.0'
  environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
  requires-python = '==3.12'
  created-by = 'mousebender'

  [[packages]]
  name = 'attrs'
  version = '25.1.0'
  requires-python = '>=3.8'

  [[packages.attestation-identities]]
  environment = 'release-pypi'
  kind = 'GitHub'
  repository = 'python-attrs/attrs'
  workflow = 'pypi-package.yml'
  
  [[packages.wheels]]
  name = 'attrs-25.1.0-py3-none-any.whl'
  upload-time = 2025-01-25T11:30:10.164985+00:00,
  url = 'https://files.pythonhosted.org/packages/fc/30/d4986a882011f9df997a55e6becd864812ccfcd821d64aac8570ee39f719/attrs-25.1.0-py3-none-any.whl'
  size = 63152
  hashes = {sha256 = 'c75a69e28a550a7e93789579c22aa26b0f5b83b75dc4e08fe092980051e1090a'}

  [[packages]]
  name = 'cattrs'
  version = '24.1.2'
  requires-python = '>=3.8'
  dependencies = [
    {name = 'attrs'},
  ]

  [[packages.wheels]]
  name = 'cattrs-24.1.2-py3-none-any.whl'
  upload-time = 2024-09-22T14:58:34.812643+00:00
  url = 'https://files.pythonhosted.org/packages/c8/d5/867e75361fc45f6de75fe277dd085627a9db5ebb511a87f27dc1396b5351/cattrs-24.1.2-py3-none-any.whl'
  size = 66446
  hashes = {sha256 = '67c7495b760168d931a10233f979b28dc04daf853b30752246f4f8471c6d68d0'}

  [[packages]]
  name = 'numpy'
  version = '2.2.3'
  requires-python = '>=3.10'

  [[packages.wheels]]
  name = 'numpy-2.2.3-cp312-cp312-win_amd64.whl'
  upload-time = 2025-02-13T16:51:21.821880+00:00
  url = 'https://files.pythonhosted.org/packages/42/6e/55580a538116d16ae7c9aa17d4edd56e83f42126cb1dfe7a684da7925d2c/numpy-2.2.3-cp312-cp312-win_amd64.whl'
  size = 12626357
  hashes = {sha256 = '83807d445817326b4bcdaaaf8e8e9f1753da04341eceec705c001ff342002e5d'}

  [[packages.wheels]]
  name = 'numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl'
  upload-time = 2025-02-13T16:50:00.079662+00:00
  url = 'https://files.pythonhosted.org/packages/39/04/78d2e7402fb479d893953fb78fa7045f7deb635ec095b6b4f0260223091a/numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl'
  size = 16116679
  hashes = {sha256 = '3b787adbf04b0db1967798dba8da1af07e387908ed1553a0d6e74c084d1ceafe'}

  [tool.mousebender]
  command = ['.', 'lock', '--platform', 'cpython3.12-windows-x64', '--platform', 'cpython3.12-manylinux2014-x64', 'cattrs', 'numpy']
  run-on = 2025-03-06T12:28:57.760769
```
created_at: 2025-04-15T14:19:52Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
- If the VCS supports commit-hash based revision identifiers, such a commit-hash,
  it MUST be used as the commit ID in order to reference an immutable version of
  the source code.
```
created_at: 2025-04-15T14:34:00Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
- The URL_ to the source tree.
```

Link reference is added below.
created_at: 2025-04-15T14:37:01Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+``[[packages.attestation-identities]]``
+---------------------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: :ref:`  provenance-object`
+- A recording of the attestations for **any** file recorded for this package.
+- If available, tools SHOULD include the attestation identities found.
+- Publisher-specific keys are to be included in the table as-is
+  (i.e. top-level), following the spec at
+  :ref:`  index-hosted-attestations`.
+
+
+``packages.attestation-identities.kind``
+''''''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`  provenance-object`
+- The unique identity of the Trusted Publisher.
+
+
+``[packages.tool]``
+-------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- Similar usage as that of the ``[tool]`` table from the
+  :ref:`  pyproject-toml-spec`, but at the package version level instead
+  of at the lock file level (which is also available via ``[tool]``).
+- Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
+  installation).
+
+
+``[tool]``
+==========
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- See ``packages.tool``.
+
+
+-------
+Example
+-------
+
+.. code-block:: TOML
+
+  lock-version = '1.0'
+  environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
+  requires-python = '==3.12'
+  created-by = 'mousebender'
+
+  [[packages]]
+  name = 'attrs'
+  version = '25.1.0'
+  requires-python = '>=3.8'
+  wheels = [
+    {name = 'attrs-25.1.0-py3-none-any.whl', upload-time = 2025-01-25T11:30:10.164985+00:00, url = 'https://files.pythonhosted.org/packages/fc/30/d4986a882011f9df997a55e6becd864812ccfcd821d64aac8570ee39f719/attrs-25.1.0-py3-none-any.whl', size = 63152, hashes = {sha256 = 'c75a69e28a550a7e93789579c22aa26b0f5b83b75dc4e08fe092980051e1090a'}},
+  ]
+  [[packages.attestation-identities]]
+  environment = 'release-pypi'
+  kind = 'GitHub'
+  repository = 'python-attrs/attrs'
+  workflow = 'pypi-package.yml'
+
+  [[packages]]
+  name = 'cattrs'
+  version = '24.1.2'
+  requires-python = '>=3.8'
+  dependencies = [
+      {name = 'attrs'},
+  ]
+  wheels = [
+    {name = 'cattrs-24.1.2-py3-none-any.whl', upload-time = 2024-09-22T14:58:34.812643+00:00, url = 'https://files.pythonhosted.org/packages/c8/d5/867e75361fc45f6de75fe277dd085627a9db5ebb511a87f27dc1396b5351/cattrs-24.1.2-py3-none-any.whl', size = 66446, hashes = {sha256 = '67c7495b760168d931a10233f979b28dc04daf853b30752246f4f8471c6d68d0'}},
+  ]
+
+  [[packages]]
+  name = 'numpy'
+  version = '2.2.3'
+  requires-python = '>=3.10'
+  wheels = [
+    {name = 'numpy-2.2.3-cp312-cp312-win_amd64.whl', upload-time = 2025-02-13T16:51:21.821880+00:00, url = 'https://files.pythonhosted.org/packages/42/6e/55580a538116d16ae7c9aa17d4edd56e83f42126cb1dfe7a684da7925d2c/numpy-2.2.3-cp312-cp312-win_amd64.whl', size = 12626357, hashes = {sha256 = '83807d445817326b4bcdaaaf8e8e9f1753da04341eceec705c001ff342002e5d'}},
+    {name = 'numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', upload-time = 2025-02-13T16:50:00.079662+00:00, url = 'https://files.pythonhosted.org/packages/39/04/78d2e7402fb479d893953fb78fa7045f7deb635ec095b6b4f0260223091a/numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', size = 16116679, hashes = {sha256 = '3b787adbf04b0db1967798dba8da1af07e387908ed1553a0d6e74c084d1ceafe'}},
+  ]
+
+  [tool.mousebender]
+  command = ['.', 'lock', '--platform', 'cpython3.12-windows-x64', '--platform', 'cpython3.12-manylinux2014-x64', 'cattrs', 'numpy']
+  run-on = 2025-03-06T12:28:57.760769
+
+
+------------
+Installation
+------------
+
+The following outlines the steps to be taken to install from a lock file
+(while the requirements are prescriptive, the general steps and order are
+a suggestion):
+
+#. Gather the extras and dependency groups to install and set ``extras`` and
+   ``dependency_groups`` for marker evaluation, respectively.
+
+   #. ``extras`` SHOULD be set to the empty set by default.
+   #. ``dependency_groups`` SHOULD be the set created from ``default-groups`` by
+      default.
+
+#. Check if the metadata version specified by ``lock-version`` is supported;
+   an error or warning MUST be raised as appropriate.
+#. If ``requires-python`` is specified, check that the environment being
+   installed for meets the requirement; an error MUST be raised if it is not
+   met.
+#. If ``environments`` is specified, check that at least one of the environment
+   marker expressions is satisfied; an error MUST be raised if no expression is
+   satisfied.
+#. For each package listed in ``[[packages]]``:
+
+   #. If ``marker`` is specified, check if it is satisfied; if it isn't,
+      skip to the next package.
+   #. If ``requires-python`` is specified, check if it is satisfied; an error
+      MUST be raised if it isn't.
+   #. Check that no other conflicting instance of the package has been slated to
+      be installed; an error about the ambiguity MUST be raised otherwise.
+   #. Check that the source of the package is specified appropriately (i.e.
+      there are no conflicting sources in the package entry);
+      an error MUST be raised if any issues are found.
+   #. Add the package to the set of packages to install.
+
+#. For each package to be installed:
+
+   - If ``vcs`` is set:
+
+     #. Clone the repository to the commit ID specified in ``commit-id``.
+     #. Build the package, respecting ``subdirectory``.
+     #. Install.
+
+   - Else if ``directory`` is set:
+
+     #. Build the package, respecting ``subdirectory``.
+     #. Install.
+
+   - Else if ``archive`` is set:
+
+     #. Get the file.
+     #. Validate the file size and hash.
+     #. Build the package, respecting ``subdirectory``.
+     #. Install.
+
+   - Else if there are entries for ``wheels``:
+
+     #. Look for the appropriate wheel file based on ``name``; if one is not
+        found then move on to ``sdist`` or an error MUST be raised about a
+        lack of source for the project.
+     #. Get the file:
+
+        - If ``path`` is set, use it.
+        - If ``url`` is set, try to use it; optionally tools MAY use
+          ``packages.index`` or some tool-specific mechanism to download the
+          selected wheel file (tools MUST NOT try to change what wheel file to
+          download based on what's available; what file to install should be
+          determined in an offline fashion for reproducibility).
+
+     #. Validate the file size and hash.
+     #. Install.
+
+   - Else if no ``wheel`` file is found or ``sdist`` is solely set:
+
+     #. Get the file.
+
+        - If ``path`` is set, use it.
+        - If ``url`` is set, try to use it; tools MAY use
+          ``packages.index`` or some tool-specific mechanism to download the
+          file.
+
+     #. Validate the file size and hash.
+     #. Build the package.
+     #. Install.
+
+
+-------
+History
+-------
+
+- April 2025: Initial version, approved via :pep:`751`.
+
+
+.. _Content-Length: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Length
+.. _Dependabot: https://docs.github.com/en/code-security/dependabot
+.. _HEAD: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD
+.. _PDM: https://pypi.org/project/pdm/
+.. _pip-tools: https://pypi.org/project/pip-tools/
+.. _Poetry: https://python-poetry.org/
+.. _requirements file:
+.. _requirements files: https://pip.pypa.io/en/stable/reference/requirements-file-format/
+.. _software bill of materials: https://www.cisa.gov/sbom
+.. _TOML: https://toml.io/
+.. _uv: https://github.com/astral-sh/uv
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _uv: https://github.com/astral-sh/uv
.. _URL: https://url.spec.whatwg.org/
```
created_at: 2025-04-15T14:37:43Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: I think we should we should link to the relevant field in these situations.

I'll add code suggestions after the review, as it involves a lot of small changes (adding the labels, and updating the fields to reference them).
created_at: 2025-04-15T14:42:59Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-lock-version:
``lock-version``
```
created_at: 2025-04-15T14:57:39Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-environments:
``environments``
```
created_at: 2025-04-15T14:58:17Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-requires-python:
``requires-python``
```
created_at: 2025-04-15T14:58:46Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-extras:
``extras``
```
created_at: 2025-04-15T14:59:03Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-dependency-groups:
``dependency-groups``
```
created_at: 2025-04-15T14:59:19Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-default-groups:
``default-groups``
```
created_at: 2025-04-15T14:59:35Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-created-by:
``created-by``
```
created_at: 2025-04-15T14:59:50Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages:
``[[packages]]``
```
created_at: 2025-04-15T15:00:06Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-name:
``packages.name``
```
created_at: 2025-04-15T15:00:19Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-version:
``packages.version``
```
created_at: 2025-04-15T15:00:35Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-marker:
``packages.marker``
```
created_at: 2025-04-15T15:00:53Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-requires-python:
``packages.requires-python``
```
created_at: 2025-04-15T15:01:15Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-dependencies:
``[[packages.dependencies]]``
```
created_at: 2025-04-15T15:01:32Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-vcs:
``[packages.vcs]``
```
created_at: 2025-04-15T15:01:49Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-vcs-type:
``packages.vcs.type``
```
created_at: 2025-04-15T15:02:09Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-vcs-url:
``packages.vcs.url``
```
created_at: 2025-04-15T15:02:39Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-vcs-path:
``packages.vcs.path``
```
created_at: 2025-04-15T15:02:56Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-vcs-requested-revision:
``packages.vcs.requested-revision``
```
created_at: 2025-04-15T15:03:16Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-vcs-commit-id:
``packages.vcs.commit-id``
```
created_at: 2025-04-15T15:03:33Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-vcs-subdirectory:
``packages.vcs.subdirectory``
```
created_at: 2025-04-15T15:03:53Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-directory:
``[packages.directory]``
```
created_at: 2025-04-15T15:04:12Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-directory-path:
``packages.directory.path``
```
created_at: 2025-04-15T15:04:30Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-directory-editable:
``packages.directory.editable``
```
created_at: 2025-04-15T15:04:43Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-directory-subdirectory:
``packages.directory.subdirectory``
```
created_at: 2025-04-15T15:04:58Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-archive:
``[packages.archive]``
```
created_at: 2025-04-15T15:05:17Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-archive-url:
``packages.archive.url``
```
created_at: 2025-04-15T15:05:38Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-archive-path:
``packages.archive.path``
```
created_at: 2025-04-15T15:06:01Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-archive-size:
``packages.archive.size``
```
created_at: 2025-04-15T15:06:17Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-archive-upload-time:
``packages.archive.upload-time``
```
created_at: 2025-04-15T15:06:31Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-archive-hashes:
``[packages.archive.hashes]``
```
created_at: 2025-04-15T15:06:49Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-archive-subdirectory:
``packages.archive.subdirectory``
```
created_at: 2025-04-15T15:07:04Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-index:
``packages.index``
```
created_at: 2025-04-15T15:07:24Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-sdist:
``[packages.sdist]``
```
created_at: 2025-04-15T15:07:39Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-sdist-name:
``packages.sdist.name``
```
created_at: 2025-04-15T15:07:57Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-sdist-upload-time:
``packages.sdist.upload-time``
```
created_at: 2025-04-15T15:08:17Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-sdist-url:
``packages.sdist.url``
```
created_at: 2025-04-15T15:08:40Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-sdist-path:
``packages.sdist.path``
```
created_at: 2025-04-15T15:08:58Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-sdist-size:
``packages.sdist.size``
```
created_at: 2025-04-15T15:09:16Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-sdist-hashes:
``packages.sdist.hashes``
```
created_at: 2025-04-15T15:09:33Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-wheels:
``[[packages.wheels]]``
```
created_at: 2025-04-15T15:09:53Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-wheels-name:
``packages.wheels.name``
```
created_at: 2025-04-15T15:10:09Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-wheels-upload-time:
``packages.wheels.upload-time``
```
created_at: 2025-04-15T15:10:27Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-wheels-url:
``packages.wheels.url``
```
created_at: 2025-04-15T15:10:42Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-wheels-path:
``packages.wheels.path``
```
created_at: 2025-04-15T15:11:02Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.wheels.size``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-wheels-size:
``packages.wheels.size``
```
created_at: 2025-04-15T15:11:18Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.wheels.hashes``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-wheels-hashes:
``packages.wheels.hashes``
```
created_at: 2025-04-15T15:11:33Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+``[[packages.attestation-identities]]``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-attestation-identities:
``[[packages.attestation-identities]]``
```
created_at: 2025-04-15T15:11:52Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+``[[packages.attestation-identities]]``
+---------------------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: :ref:`  provenance-object`
+- A recording of the attestations for **any** file recorded for this package.
+- If available, tools SHOULD include the attestation identities found.
+- Publisher-specific keys are to be included in the table as-is
+  (i.e. top-level), following the spec at
+  :ref:`  index-hosted-attestations`.
+
+
+``packages.attestation-identities.kind``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages-attestation-identities-kind:
``packages.attestation-identities.kind``
```
created_at: 2025-04-15T15:12:09Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+``[[packages.attestation-identities]]``
+---------------------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: :ref:`  provenance-object`
+- A recording of the attestations for **any** file recorded for this package.
+- If available, tools SHOULD include the attestation identities found.
+- Publisher-specific keys are to be included in the table as-is
+  (i.e. top-level), following the spec at
+  :ref:`  index-hosted-attestations`.
+
+
+``packages.attestation-identities.kind``
+''''''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`  provenance-object`
+- The unique identity of the Trusted Publisher.
+
+
+``[packages.tool]``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-packages.tool:
``[packages.tool]``
```
created_at: 2025-04-15T15:12:27Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+``[[packages.attestation-identities]]``
+---------------------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: :ref:`  provenance-object`
+- A recording of the attestations for **any** file recorded for this package.
+- If available, tools SHOULD include the attestation identities found.
+- Publisher-specific keys are to be included in the table as-is
+  (i.e. top-level), following the spec at
+  :ref:`  index-hosted-attestations`.
+
+
+``packages.attestation-identities.kind``
+''''''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`  provenance-object`
+- The unique identity of the Trusted Publisher.
+
+
+``[packages.tool]``
+-------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- Similar usage as that of the ``[tool]`` table from the
+  :ref:`  pyproject-toml-spec`, but at the package version level instead
+  of at the lock file level (which is also available via ``[tool]``).
+- Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
+  installation).
+
+
+``[tool]``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
.. _pylock-tool:
``[tool]``
```
created_at: 2025-04-15T15:12:41Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
- The name of synthetic dependency groups to represent what should be installed
  by default (e.g. what ``project.dependencies`` implicitly represents).
- Meant to be used in situations where :ref:`pylock-packages.marker` necessitates such a
  group to exist.
- The groups listed by this key SHOULD NOT be listed in :ref:`pylock-dependency-groups` as
  the groups are not meant to be directly exposed to users by name but instead
  via an installer's UI.
```
created_at: 2025-04-15T15:20:36Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
- Records the name of the tool used to create the lock file.
- Tools MAY use the :ref:`pylock-tool` table to record enough details that it can be
  inferred what inputs were used to create the lock file.
- Tools SHOULD record the normalized name of the tool if it is available as a
  Python package to facilitate finding the tool.
```
created_at: 2025-04-15T15:21:03Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
- Records the other entries in :ref:`pylock-packages` which are direct dependencies of
  this package.
- Each entry is a table which contains the minimum information required to tell
  which other package entry it corresponds to where doing a key-by-key
  comparison would find the appropriate package with no ambiguity (e.g. if there
  are two entries for the ``spam`` package, then you can include the version
  number like ``{name = "spam", version = "1.0.0"}``, or by source like
  ``{name = "spam", vcs = { url = "..."}``).
- Tools MUST NOT use this information when doing installation; it is purely
  informational for auditing purposes.
```
created_at: 2025-04-15T15:21:41Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and :ref:`pylock-packages.wheels`
```
created_at: 2025-04-15T15:23:00Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
See :ref:`pylock-packages-vcs-url`.
```
created_at: 2025-04-15T15:23:34Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
See :ref:`pylock-packages-vcs-path`.
```
created_at: 2025-04-15T15:23:52Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
See :ref:`pylock-packages-vcs-subdirectory`.
```
created_at: 2025-04-15T15:24:24Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
  :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
```
created_at: 2025-04-15T15:25:03Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
- **Required?**: no, not when the last component of :ref:`pylock-sdist-path`/ :ref:`pylock-sdist-url` would be
  the same value
```
created_at: 2025-04-15T15:26:09Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
See :ref:`pylock-packages-archive-upload-time`.
```
created_at: 2025-04-15T15:26:28Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
See :ref:`pylock-packages-archive-url`.
```
created_at: 2025-04-15T15:26:43Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
See :ref:`pylock-packages-archive-path`.
```
created_at: 2025-04-15T15:26:58Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
See :ref:`pylock-packages-archive-size`.
```
created_at: 2025-04-15T15:27:10Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
See :ref:`pylock-packages-archive-hashes`.
```
created_at: 2025-04-15T15:27:24Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
  :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
```
created_at: 2025-04-15T15:27:54Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
- **Required?**: no, not when the last component of :ref:`pylock-wheels-path`/ :ref:`pylock-wheels-url` would be
  the same value
```
created_at: 2025-04-15T15:28:25Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
See :ref:`pylock-packages-archive-upload-time`.
```
created_at: 2025-04-15T15:28:41Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
See :ref:`pylock-packages-archive-url`.
```
created_at: 2025-04-15T15:29:00Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
See :ref:`pylock-packages-archive-path`.
```
created_at: 2025-04-15T15:29:15Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See ``packages.archive.size``.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
See :ref:`pylock-packages-archive-size`.
```
created_at: 2025-04-15T15:29:26Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
See :ref:`pylock-packages-archive-hashes`.
```
created_at: 2025-04-15T15:29:40Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+``[[packages.attestation-identities]]``
+---------------------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: :ref:`  provenance-object`
+- A recording of the attestations for **any** file recorded for this package.
+- If available, tools SHOULD include the attestation identities found.
+- Publisher-specific keys are to be included in the table as-is
+  (i.e. top-level), following the spec at
+  :ref:`  index-hosted-attestations`.
+
+
+``packages.attestation-identities.kind``
+''''''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`  provenance-object`
+- The unique identity of the Trusted Publisher.
+
+
+``[packages.tool]``
+-------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- Similar usage as that of the ``[tool]`` table from the
+  :ref:`  pyproject-toml-spec`, but at the package version level instead
+  of at the lock file level (which is also available via ``[tool]``).
+- Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
+  installation).
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
- Similar usage as that of the ``[tool]`` table from the
  :ref:`  pyproject-toml-spec`, but at the package version level instead
  of at the lock file level (which is also available via :ref:`pylock-tool`).
- Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
  installation).
```
created_at: 2025-04-15T15:30:39Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+``[[packages.attestation-identities]]``
+---------------------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: :ref:`  provenance-object`
+- A recording of the attestations for **any** file recorded for this package.
+- If available, tools SHOULD include the attestation identities found.
+- Publisher-specific keys are to be included in the table as-is
+  (i.e. top-level), following the spec at
+  :ref:`  index-hosted-attestations`.
+
+
+``packages.attestation-identities.kind``
+''''''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`  provenance-object`
+- The unique identity of the Trusted Publisher.
+
+
+``[packages.tool]``
+-------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- Similar usage as that of the ``[tool]`` table from the
+  :ref:`  pyproject-toml-spec`, but at the package version level instead
+  of at the lock file level (which is also available via ``[tool]``).
+- Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
+  installation).
+
+
+``[tool]``
+==========
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- See ``packages.tool``.
path: source/specifications/pylock-toml.rst
user: login: FFY00
body: ```suggestion
- See :ref:`pylock-packages-tool`.
```
created_at: 2025-04-15T15:30:55Z
author_association: MEMBER
diff_hunk: @@ -235,52 +236,80 @@ no current specification for this. Regardless, outside of a context where this
 special handling is taking place, the "extra" variable should result in an
 error like all other unknown variables.
 
+The "extras" and "dependency_groups" variables are also special. They are used
+to specify any requested extras or dependency groups when installing from a lock
+file. Outside of the context of lock files, these two variables should result in
+an error like all other unknown variables.
+
 .. list-table::
    :header-rows: 1
 
    * - Marker
      - Python equivalent
+     - Type
      - Sample values
    * - ``os_name``
      - :py:data:`os.name`
+     - String
      - ``posix``, ``java``
    * - ``sys_platform``
      - :py:data:`sys.platform`
+     - String
      - ``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that "linux"
        is from Python3 and "linux2" from Python2)
    * - ``platform_machine``
      - :py:func:`platform.machine()`
+     - String
      - ``x86_64``
    * - ``platform_python_implementation``
      - :py:func:`platform.python_implementation()`
+     - String
      - ``CPython``, ``Jython``
    * - ``platform_release``
      - :py:func:`platform.release()`
+     - String
      - ``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``
    * - ``platform_system``
      - :py:func:`platform.system()`
+     - String
      - ``Linux``, ``Windows``, ``Java``
    * - ``platform_version``
      - :py:func:`platform.version()`
+     - String
      - ``#1 SMP Fri Apr 25 13:07:35 EDT 2014``
        ``Java HotSpot(TM) 64-Bit Server VM, 25.51-b03, Oracle Corporation``
        ``Darwin Kernel Version 14.5.0: Wed Jul 29 02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``
    * - ``python_version``
      - ``'.'.join(platform.python_version_tuple()[:2])``
+     - Version
path: source/specifications/dependency-specifiers.rst
user: login: FFY00
body: ```suggestion
     - :ref:`Version <version-specifiers>`
```
created_at: 2025-04-15T15:35:53Z
author_association: MEMBER
diff_hunk: @@ -235,52 +236,80 @@ no current specification for this. Regardless, outside of a context where this
 special handling is taking place, the "extra" variable should result in an
 error like all other unknown variables.
 
+The "extras" and "dependency_groups" variables are also special. They are used
+to specify any requested extras or dependency groups when installing from a lock
+file. Outside of the context of lock files, these two variables should result in
+an error like all other unknown variables.
+
 .. list-table::
    :header-rows: 1
 
    * - Marker
      - Python equivalent
+     - Type
      - Sample values
    * - ``os_name``
      - :py:data:`os.name`
+     - String
      - ``posix``, ``java``
    * - ``sys_platform``
      - :py:data:`sys.platform`
+     - String
      - ``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that "linux"
        is from Python3 and "linux2" from Python2)
    * - ``platform_machine``
      - :py:func:`platform.machine()`
+     - String
      - ``x86_64``
    * - ``platform_python_implementation``
      - :py:func:`platform.python_implementation()`
+     - String
      - ``CPython``, ``Jython``
    * - ``platform_release``
      - :py:func:`platform.release()`
+     - String
      - ``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``
    * - ``platform_system``
      - :py:func:`platform.system()`
+     - String
      - ``Linux``, ``Windows``, ``Java``
    * - ``platform_version``
      - :py:func:`platform.version()`
+     - String
      - ``#1 SMP Fri Apr 25 13:07:35 EDT 2014``
        ``Java HotSpot(TM) 64-Bit Server VM, 25.51-b03, Oracle Corporation``
        ``Darwin Kernel Version 14.5.0: Wed Jul 29 02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``
    * - ``python_version``
      - ``'.'.join(platform.python_version_tuple()[:2])``
+     - Version
      - ``3.4``, ``2.7``
    * - ``python_full_version``
      - :py:func:`platform.python_version()`
+     - Version
path: source/specifications/dependency-specifiers.rst
user: login: FFY00
body: ```suggestion
     - :ref:`Version <version-specifiers>`
```
created_at: 2025-04-15T15:36:02Z
author_association: MEMBER
diff_hunk: @@ -235,52 +236,80 @@ no current specification for this. Regardless, outside of a context where this
 special handling is taking place, the "extra" variable should result in an
 error like all other unknown variables.
 
+The "extras" and "dependency_groups" variables are also special. They are used
+to specify any requested extras or dependency groups when installing from a lock
+file. Outside of the context of lock files, these two variables should result in
+an error like all other unknown variables.
+
 .. list-table::
    :header-rows: 1
 
    * - Marker
      - Python equivalent
+     - Type
      - Sample values
    * - ``os_name``
      - :py:data:`os.name`
+     - String
      - ``posix``, ``java``
    * - ``sys_platform``
      - :py:data:`sys.platform`
+     - String
      - ``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that "linux"
        is from Python3 and "linux2" from Python2)
    * - ``platform_machine``
      - :py:func:`platform.machine()`
+     - String
      - ``x86_64``
    * - ``platform_python_implementation``
      - :py:func:`platform.python_implementation()`
+     - String
      - ``CPython``, ``Jython``
    * - ``platform_release``
      - :py:func:`platform.release()`
+     - String
      - ``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``
    * - ``platform_system``
      - :py:func:`platform.system()`
+     - String
      - ``Linux``, ``Windows``, ``Java``
    * - ``platform_version``
      - :py:func:`platform.version()`
+     - String
      - ``#1 SMP Fri Apr 25 13:07:35 EDT 2014``
        ``Java HotSpot(TM) 64-Bit Server VM, 25.51-b03, Oracle Corporation``
        ``Darwin Kernel Version 14.5.0: Wed Jul 29 02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``
    * - ``python_version``
      - ``'.'.join(platform.python_version_tuple()[:2])``
+     - Version
      - ``3.4``, ``2.7``
    * - ``python_full_version``
      - :py:func:`platform.python_version()`
+     - Version
      - ``3.4.0``, ``3.5.0b1``
    * - ``implementation_name``
      - :py:data:`sys.implementation.name <sys.implementation>`
+     - String
      - ``cpython``
    * - ``implementation_version``
      - see definition below
+     - Version
path: source/specifications/dependency-specifiers.rst
user: login: FFY00
body: ```suggestion
     - :ref:`Version <version-specifiers>`
```
created_at: 2025-04-15T15:36:09Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+``[[packages.attestation-identities]]``
+---------------------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: :ref:`  provenance-object`
+- A recording of the attestations for **any** file recorded for this package.
+- If available, tools SHOULD include the attestation identities found.
+- Publisher-specific keys are to be included in the table as-is
+  (i.e. top-level), following the spec at
+  :ref:`  index-hosted-attestations`.
+
+
+``packages.attestation-identities.kind``
+''''''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`  provenance-object`
+- The unique identity of the Trusted Publisher.
+
+
+``[packages.tool]``
+-------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- Similar usage as that of the ``[tool]`` table from the
+  :ref:`  pyproject-toml-spec`, but at the package version level instead
+  of at the lock file level (which is also available via ``[tool]``).
+- Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
+  installation).
+
+
+``[tool]``
+==========
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- See ``packages.tool``.
+
+
+-------
+Example
+-------
+
+.. code-block:: TOML
+
+  lock-version = '1.0'
+  environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
+  requires-python = '==3.12'
+  created-by = 'mousebender'
+
+  [[packages]]
+  name = 'attrs'
+  version = '25.1.0'
+  requires-python = '>=3.8'
+  wheels = [
+    {name = 'attrs-25.1.0-py3-none-any.whl', upload-time = 2025-01-25T11:30:10.164985+00:00, url = 'https://files.pythonhosted.org/packages/fc/30/d4986a882011f9df997a55e6becd864812ccfcd821d64aac8570ee39f719/attrs-25.1.0-py3-none-any.whl', size = 63152, hashes = {sha256 = 'c75a69e28a550a7e93789579c22aa26b0f5b83b75dc4e08fe092980051e1090a'}},
+  ]
+  [[packages.attestation-identities]]
+  environment = 'release-pypi'
+  kind = 'GitHub'
+  repository = 'python-attrs/attrs'
+  workflow = 'pypi-package.yml'
+
+  [[packages]]
+  name = 'cattrs'
+  version = '24.1.2'
+  requires-python = '>=3.8'
+  dependencies = [
+      {name = 'attrs'},
+  ]
+  wheels = [
+    {name = 'cattrs-24.1.2-py3-none-any.whl', upload-time = 2024-09-22T14:58:34.812643+00:00, url = 'https://files.pythonhosted.org/packages/c8/d5/867e75361fc45f6de75fe277dd085627a9db5ebb511a87f27dc1396b5351/cattrs-24.1.2-py3-none-any.whl', size = 66446, hashes = {sha256 = '67c7495b760168d931a10233f979b28dc04daf853b30752246f4f8471c6d68d0'}},
+  ]
+
+  [[packages]]
+  name = 'numpy'
+  version = '2.2.3'
+  requires-python = '>=3.10'
+  wheels = [
+    {name = 'numpy-2.2.3-cp312-cp312-win_amd64.whl', upload-time = 2025-02-13T16:51:21.821880+00:00, url = 'https://files.pythonhosted.org/packages/42/6e/55580a538116d16ae7c9aa17d4edd56e83f42126cb1dfe7a684da7925d2c/numpy-2.2.3-cp312-cp312-win_amd64.whl', size = 12626357, hashes = {sha256 = '83807d445817326b4bcdaaaf8e8e9f1753da04341eceec705c001ff342002e5d'}},
+    {name = 'numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', upload-time = 2025-02-13T16:50:00.079662+00:00, url = 'https://files.pythonhosted.org/packages/39/04/78d2e7402fb479d893953fb78fa7045f7deb635ec095b6b4f0260223091a/numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', size = 16116679, hashes = {sha256 = '3b787adbf04b0db1967798dba8da1af07e387908ed1553a0d6e74c084d1ceafe'}},
+  ]
+
+  [tool.mousebender]
+  command = ['.', 'lock', '--platform', 'cpython3.12-windows-x64', '--platform', 'cpython3.12-manylinux2014-x64', 'cattrs', 'numpy']
+  run-on = 2025-03-06T12:28:57.760769
path: source/specifications/pylock-toml.rst
user: login: brettcannon
body: I'm a bit concerned about taking this without updating a tool or having something programmatically make sure it's equivalent to what was there before. Beyond that I'm indifferent as it's an example and not an official bit of the spec that people must match.
created_at: 2025-04-15T20:39:30Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,892 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-directory-path:
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+.. _pylock-packages-directory-editable:
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+.. _pylock-packages-directory-subdirectory:
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-archive:
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-archive-url:
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-url`.
+
+
+.. _pylock-packages-archive-path:
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-path`.
+
+
+.. _pylock-packages-archive-size:
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+.. _pylock-packages-archive-upload-time:
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+.. _pylock-packages-archive-hashes:
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+.. _pylock-packages-archive-subdirectory:
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-index:
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+.. _pylock-packages-sdist:
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+.. _pylock-packages-sdist-name:
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of
+  :ref:`pylock-packages-sdist-path`/ :ref:`pylock-packages-sdist-url` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+.. _pylock-packages-sdist-upload-time:
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-upload-time`.
+
+
+.. _pylock-packages-sdist-url:
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-url`.
+
+
+.. _pylock-packages-sdist-path:
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-path`.
+
+
+.. _pylock-packages-sdist-size:
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-size`.
+
+
+.. _pylock-packages-sdist-hashes:
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-hashes`.
+
+
+
+.. _pylock-packages-wheels:
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+.. _pylock-packages-wheels-name:
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of
+  :ref:`pylock-packages-wheels-path`/ :ref:`pylock-packages-wheels-url` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`binary-distribution-format` file.
+
+
+.. _pylock-packages-wheels-upload-time:
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-upload-time`.
+
+
+.. _pylock-packages-wheels-url:
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-url`.
+
+
+.. _pylock-packages-wheels-path:
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-path`.
+
+
+.. _pylock-packages-wheels-size:
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-size`.
+
+
+.. _pylock-packages-wheels-hashes:
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-hashes`.
+
+
+.. _pylock-packages-attestation-identities:
+
+``[[packages.attestation-identities]]``
+---------------------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: :ref:`  provenance-object`
+- A recording of the attestations for **any** file recorded for this package.
+- If available, tools SHOULD include the attestation identities found.
+- Publisher-specific keys are to be included in the table as-is
+  (i.e. top-level), following the spec at
+  :ref:`  index-hosted-attestations`.
+
+
+.. _pylock-packages-attestation-identities-kind:
+
+``packages.attestation-identities.kind``
+''''''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`  provenance-object`
+- The unique identity of the Trusted Publisher.
+
+
+.. _pylock-packages-tool:
+
+``[packages.tool]``
+-------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- Similar usage as that of the :ref:`pylock-tool` table from the
+  :ref:`  pyproject-toml-spec`, but at the package version level instead
+  of at the lock file level (which is also available via :ref:`pylock-tool`).
+- Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
+  installation).
+
+
+.. _pylock-tool:
+
+``[tool]``
+==========
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`pyproject-tool-table`
+- See :ref:`pylock-packages-tool`.
+
+
+-------
+Example
+-------
+
+.. code-block:: TOML
+
+  lock-version = '1.0'
+  environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
+  requires-python = '==3.12'
+  created-by = 'mousebender'
+
+  [[packages]]
+  name = 'attrs'
+  version = '25.1.0'
+  requires-python = '>=3.8'
+  wheels = [
+    {name = 'attrs-25.1.0-py3-none-any.whl', upload-time = 2025-01-25T11:30:10.164985+00:00, url = 'https://files.pythonhosted.org/packages/fc/30/d4986a882011f9df997a55e6becd864812ccfcd821d64aac8570ee39f719/attrs-25.1.0-py3-none-any.whl', size = 63152, hashes = {sha256 = 'c75a69e28a550a7e93789579c22aa26b0f5b83b75dc4e08fe092980051e1090a'}},
+  ]
+  [[packages.attestation-identities]]
+  environment = 'release-pypi'
+  kind = 'GitHub'
+  repository = 'python-attrs/attrs'
+  workflow = 'pypi-package.yml'
+
+  [[packages]]
+  name = 'cattrs'
+  version = '24.1.2'
+  requires-python = '>=3.8'
+  dependencies = [
+      {name = 'attrs'},
+  ]
+  wheels = [
+    {name = 'cattrs-24.1.2-py3-none-any.whl', upload-time = 2024-09-22T14:58:34.812643+00:00, url = 'https://files.pythonhosted.org/packages/c8/d5/867e75361fc45f6de75fe277dd085627a9db5ebb511a87f27dc1396b5351/cattrs-24.1.2-py3-none-any.whl', size = 66446, hashes = {sha256 = '67c7495b760168d931a10233f979b28dc04daf853b30752246f4f8471c6d68d0'}},
+  ]
+
+  [[packages]]
+  name = 'numpy'
+  version = '2.2.3'
+  requires-python = '>=3.10'
+  wheels = [
+    {name = 'numpy-2.2.3-cp312-cp312-win_amd64.whl', upload-time = 2025-02-13T16:51:21.821880+00:00, url = 'https://files.pythonhosted.org/packages/42/6e/55580a538116d16ae7c9aa17d4edd56e83f42126cb1dfe7a684da7925d2c/numpy-2.2.3-cp312-cp312-win_amd64.whl', size = 12626357, hashes = {sha256 = '83807d445817326b4bcdaaaf8e8e9f1753da04341eceec705c001ff342002e5d'}},
+    {name = 'numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', upload-time = 2025-02-13T16:50:00.079662+00:00, url = 'https://files.pythonhosted.org/packages/39/04/78d2e7402fb479d893953fb78fa7045f7deb635ec095b6b4f0260223091a/numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', size = 16116679, hashes = {sha256 = '3b787adbf04b0db1967798dba8da1af07e387908ed1553a0d6e74c084d1ceafe'}},
+  ]
+
+  [tool.mousebender]
+  command = ['.', 'lock', '--platform', 'cpython3.12-windows-x64', '--platform', 'cpython3.12-manylinux2014-x64', 'cattrs', 'numpy']
+  run-on = 2025-03-06T12:28:57.760769
+
+
+------------
+Installation
+------------
+
+The following outlines the steps to be taken to install from a lock file
+(while the requirements are prescriptive, the general steps and order are
+a suggestion):
+
+#. Gather the extras and dependency groups to install and set ``extras`` and
+   ``dependency_groups`` for marker evaluation, respectively.
+
+   #. ``extras`` SHOULD be set to the empty set by default.
+   #. ``dependency_groups`` SHOULD be the set created from
+      :ref:`pylock-default-groups` by default.
+
+#. Check if the metadata version specified by :ref:`pylock-lock-version` is
+   supported; an error or warning MUST be raised as appropriate.
+#. If :ref:`pylock-requires-python` is specified, check that the environment
+   being installed for meets the requirement; an error MUST be raised if it is
+   not met.
+#. If :ref:`pylock-environments` is specified, check that at least one of the
+   environment marker expressions is satisfied; an error MUST be raised if no
+   expression is satisfied.
+#. For each package listed in :ref:`pylock-packages`:
+
+   #. If :ref:`pylock-packages-marker` is specified, check if it is satisfied;
+      if it isn't, skip to the next package.
+   #. If :ref:`pylock-packages-requires-python` is specified, check if it is
+      satisfied; an error MUST be raised if it isn't.
+   #. Check that no other conflicting instance of the package has been slated to
+      be installed; an error about the ambiguity MUST be raised otherwise.
+   #. Check that the source of the package is specified appropriately (i.e.
+      there are no conflicting sources in the package entry);
+      an error MUST be raised if any issues are found.
+   #. Add the package to the set of packages to install.
+
+#. For each package to be installed:
+
+   - If :ref:`pylock-packages-vcs` is set:
+
+     #. Clone the repository to the commit ID specified in
+        :ref:`pylock-packages-vcs-commit-id`.
+     #. :ref:`Build <source-distribution-format-source-tree>` the package,
+        respecting :ref:`pylock-packages-vcs-subdirectory`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if :ref:`pylock-packages-directory` is set:
+
+     #. :ref:`Build <source-distribution-format-source-tree>` the package,
+        respecting :ref:`pylock-packages-directory-subdirectory`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if :ref:`pylock-packages-archive` is set:
+
+     #. Get the file.
+     #. Validate using :ref:`pylock-packages-archive-size` and
+        :ref:`pylock-packages-archive-hashes`.
+     #. :ref:`Build <source-distribution-format-source-tree>` the package,
+        respecting :ref:`pylock-packages-archive-subdirectory`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if there are entries for :ref:`pylock-packages-wheels`:
+
+     #. Look for the appropriate wheel file based on
+        :ref:`pylock-packages-wheels-name`; if one is not found then move on to
+        :ref:`pylock-packages-sdist` or an error MUST be raised about a
+        lack of source for the project.
+     #. Get the file:
+
+        - If :ref:`pylock-packages-wheels-path` is set, use it.
+        - Else if :ref:`pylock-packages-wheels-url` is set, try to use it;
+          optionally tools MAY use :ref:`pylock-packages-index` or some
+          tool-specific mechanism to download the selected wheel file (tools
+          MUST NOT try to change what wheel file to download based on what's
+          available; what file to install should be determined in an offline
+          fashion for reproducibility).
+
+     #. Validate using :ref:`pylock-packages-wheels-size` and
+        :ref:`pylock-packages-wheels-hashes`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if no :ref:`pylock-packages-wheels` file is found or
+     :ref:`pylock-packages-sdist` is solely set:
+
+     #. Get the file.
+
+        - If :ref:`pylock-packages-sdist-path` is set, use it.
+        - Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools
+          MAY use :ref:`pylock-packages-index` or some tool-specific mechanism
+          to download the file.
+
+     #. Validate using :ref:`pylock-packages-sdist-size` and
+        :ref:`pylock-packages-sdist-hashes`.
+     #. :ref:`Build <source-distribution-format-sdist>` the package.
+     #. :ref:`Install <binary-distribution-format>`.
+
+
+-------
+History
+-------
+
+- April 2025: Initial version, approved via :pep:`751`.
+
+
+.. _Content-Length: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Length
+.. _Dependabot: https://docs.github.com/en/code-security/dependabot
+.. _HEAD: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD
+.. _PDM: https://pypi.org/project/pdm/
+.. _pip-tools: https://pypi.org/project/pip-tools/
+.. _Poetry: https://python-poetry.org/
+.. _requirements file:
+.. _requirements files: https://pip.pypa.io/en/stable/reference/requirements-file-format/
+.. _software bill of materials: https://www.cisa.gov/sbom
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: I've restarted the linkcheck job in CI. But if it fails again, this will probably have to go into `linkcheck_ignore`.
created_at: 2025-04-16T12:41:58Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,892 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-directory-path:
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+.. _pylock-packages-directory-editable:
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+.. _pylock-packages-directory-subdirectory:
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-archive:
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-archive-url:
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-url`.
+
+
+.. _pylock-packages-archive-path:
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-path`.
+
+
+.. _pylock-packages-archive-size:
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+.. _pylock-packages-archive-upload-time:
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+.. _pylock-packages-archive-hashes:
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+.. _pylock-packages-archive-subdirectory:
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-index:
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+.. _pylock-packages-sdist:
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+.. _pylock-packages-sdist-name:
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of
+  :ref:`pylock-packages-sdist-path`/ :ref:`pylock-packages-sdist-url` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+.. _pylock-packages-sdist-upload-time:
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-upload-time`.
+
+
+.. _pylock-packages-sdist-url:
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-url`.
+
+
+.. _pylock-packages-sdist-path:
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-path`.
+
+
+.. _pylock-packages-sdist-size:
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-size`.
+
+
+.. _pylock-packages-sdist-hashes:
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-hashes`.
+
+
+
+.. _pylock-packages-wheels:
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+.. _pylock-packages-wheels-name:
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of
+  :ref:`pylock-packages-wheels-path`/ :ref:`pylock-packages-wheels-url` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`binary-distribution-format` file.
+
+
+.. _pylock-packages-wheels-upload-time:
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-upload-time`.
+
+
+.. _pylock-packages-wheels-url:
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-url`.
+
+
+.. _pylock-packages-wheels-path:
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-path`.
+
+
+.. _pylock-packages-wheels-size:
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-size`.
+
+
+.. _pylock-packages-wheels-hashes:
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-hashes`.
+
+
+.. _pylock-packages-attestation-identities:
+
+``[[packages.attestation-identities]]``
+---------------------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: :ref:`  provenance-object`
+- A recording of the attestations for **any** file recorded for this package.
+- If available, tools SHOULD include the attestation identities found.
+- Publisher-specific keys are to be included in the table as-is
+  (i.e. top-level), following the spec at
+  :ref:`  index-hosted-attestations`.
+
+
+.. _pylock-packages-attestation-identities-kind:
+
+``packages.attestation-identities.kind``
+''''''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`  provenance-object`
+- The unique identity of the Trusted Publisher.
+
+
+.. _pylock-packages-tool:
+
+``[packages.tool]``
+-------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- Similar usage as that of the :ref:`pylock-tool` table from the
+  :ref:`  pyproject-toml-spec`, but at the package version level instead
+  of at the lock file level (which is also available via :ref:`pylock-tool`).
+- Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
+  installation).
+
+
+.. _pylock-tool:
+
+``[tool]``
+==========
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`pyproject-tool-table`
+- See :ref:`pylock-packages-tool`.
+
+
+-------
+Example
+-------
+
+.. code-block:: TOML
+
+  lock-version = '1.0'
+  environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
+  requires-python = '==3.12'
+  created-by = 'mousebender'
+
+  [[packages]]
+  name = 'attrs'
+  version = '25.1.0'
+  requires-python = '>=3.8'
+  wheels = [
+    {name = 'attrs-25.1.0-py3-none-any.whl', upload-time = 2025-01-25T11:30:10.164985+00:00, url = 'https://files.pythonhosted.org/packages/fc/30/d4986a882011f9df997a55e6becd864812ccfcd821d64aac8570ee39f719/attrs-25.1.0-py3-none-any.whl', size = 63152, hashes = {sha256 = 'c75a69e28a550a7e93789579c22aa26b0f5b83b75dc4e08fe092980051e1090a'}},
+  ]
+  [[packages.attestation-identities]]
+  environment = 'release-pypi'
+  kind = 'GitHub'
+  repository = 'python-attrs/attrs'
+  workflow = 'pypi-package.yml'
+
+  [[packages]]
+  name = 'cattrs'
+  version = '24.1.2'
+  requires-python = '>=3.8'
+  dependencies = [
+      {name = 'attrs'},
+  ]
+  wheels = [
+    {name = 'cattrs-24.1.2-py3-none-any.whl', upload-time = 2024-09-22T14:58:34.812643+00:00, url = 'https://files.pythonhosted.org/packages/c8/d5/867e75361fc45f6de75fe277dd085627a9db5ebb511a87f27dc1396b5351/cattrs-24.1.2-py3-none-any.whl', size = 66446, hashes = {sha256 = '67c7495b760168d931a10233f979b28dc04daf853b30752246f4f8471c6d68d0'}},
+  ]
+
+  [[packages]]
+  name = 'numpy'
+  version = '2.2.3'
+  requires-python = '>=3.10'
+  wheels = [
+    {name = 'numpy-2.2.3-cp312-cp312-win_amd64.whl', upload-time = 2025-02-13T16:51:21.821880+00:00, url = 'https://files.pythonhosted.org/packages/42/6e/55580a538116d16ae7c9aa17d4edd56e83f42126cb1dfe7a684da7925d2c/numpy-2.2.3-cp312-cp312-win_amd64.whl', size = 12626357, hashes = {sha256 = '83807d445817326b4bcdaaaf8e8e9f1753da04341eceec705c001ff342002e5d'}},
+    {name = 'numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', upload-time = 2025-02-13T16:50:00.079662+00:00, url = 'https://files.pythonhosted.org/packages/39/04/78d2e7402fb479d893953fb78fa7045f7deb635ec095b6b4f0260223091a/numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', size = 16116679, hashes = {sha256 = '3b787adbf04b0db1967798dba8da1af07e387908ed1553a0d6e74c084d1ceafe'}},
+  ]
+
+  [tool.mousebender]
+  command = ['.', 'lock', '--platform', 'cpython3.12-windows-x64', '--platform', 'cpython3.12-manylinux2014-x64', 'cattrs', 'numpy']
+  run-on = 2025-03-06T12:28:57.760769
+
+
+------------
+Installation
+------------
+
+The following outlines the steps to be taken to install from a lock file
+(while the requirements are prescriptive, the general steps and order are
+a suggestion):
+
+#. Gather the extras and dependency groups to install and set ``extras`` and
+   ``dependency_groups`` for marker evaluation, respectively.
+
+   #. ``extras`` SHOULD be set to the empty set by default.
+   #. ``dependency_groups`` SHOULD be the set created from
+      :ref:`pylock-default-groups` by default.
+
+#. Check if the metadata version specified by :ref:`pylock-lock-version` is
+   supported; an error or warning MUST be raised as appropriate.
+#. If :ref:`pylock-requires-python` is specified, check that the environment
+   being installed for meets the requirement; an error MUST be raised if it is
+   not met.
+#. If :ref:`pylock-environments` is specified, check that at least one of the
+   environment marker expressions is satisfied; an error MUST be raised if no
+   expression is satisfied.
+#. For each package listed in :ref:`pylock-packages`:
+
+   #. If :ref:`pylock-packages-marker` is specified, check if it is satisfied;
+      if it isn't, skip to the next package.
+   #. If :ref:`pylock-packages-requires-python` is specified, check if it is
+      satisfied; an error MUST be raised if it isn't.
+   #. Check that no other conflicting instance of the package has been slated to
+      be installed; an error about the ambiguity MUST be raised otherwise.
+   #. Check that the source of the package is specified appropriately (i.e.
+      there are no conflicting sources in the package entry);
+      an error MUST be raised if any issues are found.
+   #. Add the package to the set of packages to install.
+
+#. For each package to be installed:
+
+   - If :ref:`pylock-packages-vcs` is set:
+
+     #. Clone the repository to the commit ID specified in
+        :ref:`pylock-packages-vcs-commit-id`.
+     #. :ref:`Build <source-distribution-format-source-tree>` the package,
+        respecting :ref:`pylock-packages-vcs-subdirectory`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if :ref:`pylock-packages-directory` is set:
+
+     #. :ref:`Build <source-distribution-format-source-tree>` the package,
+        respecting :ref:`pylock-packages-directory-subdirectory`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if :ref:`pylock-packages-archive` is set:
+
+     #. Get the file.
+     #. Validate using :ref:`pylock-packages-archive-size` and
+        :ref:`pylock-packages-archive-hashes`.
+     #. :ref:`Build <source-distribution-format-source-tree>` the package,
+        respecting :ref:`pylock-packages-archive-subdirectory`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if there are entries for :ref:`pylock-packages-wheels`:
+
+     #. Look for the appropriate wheel file based on
+        :ref:`pylock-packages-wheels-name`; if one is not found then move on to
+        :ref:`pylock-packages-sdist` or an error MUST be raised about a
+        lack of source for the project.
+     #. Get the file:
+
+        - If :ref:`pylock-packages-wheels-path` is set, use it.
+        - Else if :ref:`pylock-packages-wheels-url` is set, try to use it;
+          optionally tools MAY use :ref:`pylock-packages-index` or some
+          tool-specific mechanism to download the selected wheel file (tools
+          MUST NOT try to change what wheel file to download based on what's
+          available; what file to install should be determined in an offline
+          fashion for reproducibility).
+
+     #. Validate using :ref:`pylock-packages-wheels-size` and
+        :ref:`pylock-packages-wheels-hashes`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if no :ref:`pylock-packages-wheels` file is found or
+     :ref:`pylock-packages-sdist` is solely set:
+
+     #. Get the file.
+
+        - If :ref:`pylock-packages-sdist-path` is set, use it.
+        - Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools
+          MAY use :ref:`pylock-packages-index` or some tool-specific mechanism
+          to download the file.
+
+     #. Validate using :ref:`pylock-packages-sdist-size` and
+        :ref:`pylock-packages-sdist-hashes`.
+     #. :ref:`Build <source-distribution-format-sdist>` the package.
+     #. :ref:`Install <binary-distribution-format>`.
+
+
+-------
+History
+-------
+
+- April 2025: Initial version, approved via :pep:`751`.
+
+
+.. _Content-Length: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Length
+.. _Dependabot: https://docs.github.com/en/code-security/dependabot
+.. _HEAD: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD
+.. _PDM: https://pypi.org/project/pdm/
+.. _pip-tools: https://pypi.org/project/pip-tools/
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: Any reason these two point to PyPI while others point to the docs sites?
```suggestion
.. _PDM: https://pdm-project.org
.. _pip-tools: https://pip-tools.rtfd.io
```
created_at: 2025-04-16T13:30:10Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+``[[packages.attestation-identities]]``
+---------------------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: :ref:`  provenance-object`
+- A recording of the attestations for **any** file recorded for this package.
+- If available, tools SHOULD include the attestation identities found.
+- Publisher-specific keys are to be included in the table as-is
+  (i.e. top-level), following the spec at
+  :ref:`  index-hosted-attestations`.
+
+
+``packages.attestation-identities.kind``
+''''''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`  provenance-object`
+- The unique identity of the Trusted Publisher.
+
+
+``[packages.tool]``
+-------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- Similar usage as that of the ``[tool]`` table from the
+  :ref:`  pyproject-toml-spec`, but at the package version level instead
+  of at the lock file level (which is also available via ``[tool]``).
+- Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
+  installation).
+
+
+``[tool]``
+==========
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- See ``packages.tool``.
+
+
+-------
+Example
+-------
+
+.. code-block:: TOML
+
+  lock-version = '1.0'
+  environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
+  requires-python = '==3.12'
+  created-by = 'mousebender'
+
+  [[packages]]
+  name = 'attrs'
+  version = '25.1.0'
+  requires-python = '>=3.8'
+  wheels = [
+    {name = 'attrs-25.1.0-py3-none-any.whl', upload-time = 2025-01-25T11:30:10.164985+00:00, url = 'https://files.pythonhosted.org/packages/fc/30/d4986a882011f9df997a55e6becd864812ccfcd821d64aac8570ee39f719/attrs-25.1.0-py3-none-any.whl', size = 63152, hashes = {sha256 = 'c75a69e28a550a7e93789579c22aa26b0f5b83b75dc4e08fe092980051e1090a'}},
+  ]
+  [[packages.attestation-identities]]
+  environment = 'release-pypi'
+  kind = 'GitHub'
+  repository = 'python-attrs/attrs'
+  workflow = 'pypi-package.yml'
+
+  [[packages]]
+  name = 'cattrs'
+  version = '24.1.2'
+  requires-python = '>=3.8'
+  dependencies = [
+      {name = 'attrs'},
+  ]
+  wheels = [
+    {name = 'cattrs-24.1.2-py3-none-any.whl', upload-time = 2024-09-22T14:58:34.812643+00:00, url = 'https://files.pythonhosted.org/packages/c8/d5/867e75361fc45f6de75fe277dd085627a9db5ebb511a87f27dc1396b5351/cattrs-24.1.2-py3-none-any.whl', size = 66446, hashes = {sha256 = '67c7495b760168d931a10233f979b28dc04daf853b30752246f4f8471c6d68d0'}},
+  ]
+
+  [[packages]]
+  name = 'numpy'
+  version = '2.2.3'
+  requires-python = '>=3.10'
+  wheels = [
+    {name = 'numpy-2.2.3-cp312-cp312-win_amd64.whl', upload-time = 2025-02-13T16:51:21.821880+00:00, url = 'https://files.pythonhosted.org/packages/42/6e/55580a538116d16ae7c9aa17d4edd56e83f42126cb1dfe7a684da7925d2c/numpy-2.2.3-cp312-cp312-win_amd64.whl', size = 12626357, hashes = {sha256 = '83807d445817326b4bcdaaaf8e8e9f1753da04341eceec705c001ff342002e5d'}},
+    {name = 'numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', upload-time = 2025-02-13T16:50:00.079662+00:00, url = 'https://files.pythonhosted.org/packages/39/04/78d2e7402fb479d893953fb78fa7045f7deb635ec095b6b4f0260223091a/numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', size = 16116679, hashes = {sha256 = '3b787adbf04b0db1967798dba8da1af07e387908ed1553a0d6e74c084d1ceafe'}},
+  ]
+
+  [tool.mousebender]
+  command = ['.', 'lock', '--platform', 'cpython3.12-windows-x64', '--platform', 'cpython3.12-manylinux2014-x64', 'cattrs', 'numpy']
+  run-on = 2025-03-06T12:28:57.760769
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: @brettcannon maybe consider putting this into a dedicated file and using literalinclude?
created_at: 2025-04-16T13:30:56Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,772 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a ``pyproject.toml``
+  file had no ``[project.optional-dependencies]`` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a ``pyproject.toml``
+  file had no ``[dependency-groups]`` table), signalling that the lock file
+  is, in effect, multi-use even if it only looks to be single-use.
+
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what ``project.dependencies`` implicitly represents).
+- Meant to be used in situations where ``packages.marker`` necessitates such a
+  group to exist.
+- The groups listed by this key SHOULD NOT be listed in ``dependency-groups`` as
+  the groups are not meant to be directly exposed to users by name but instead
+  via an installer's UI.
+
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the ``[tool]`` table to record enough details that it can be
+  inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is
+  used).
+
+
+.. Requirements
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in ``[[packages]]`` which are direct dependencies of
+  this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.directory``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``path`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL to the source tree.
+
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if ``url`` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a commit-hash
+  MUST be used as the commit ID in order to reference an immutable version of
+  the source code.
+
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <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.
+
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.archive``, ``packages.sdist``, and ``packages.wheels``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See ``packages.vcs.url``.
+
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See ``packages.vcs.path``.
+
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See ``packages.vcs.subdirectory``.
+
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with ``packages.vcs``,
+  ``packages.directory``, and ``packages.archive``
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of ``path``/ ``url`` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`  binary-distribution-format` file.
+
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See ``packages.archive.upload-time``.
+
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See ``packages.archive.url``.
+
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See ``packages.archive.path``.
+
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See ``packages.archive.size``.
+
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See ``packages.archive.hashes``.
+
+
+``[[packages.attestation-identities]]``
+---------------------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: :ref:`  provenance-object`
+- A recording of the attestations for **any** file recorded for this package.
+- If available, tools SHOULD include the attestation identities found.
+- Publisher-specific keys are to be included in the table as-is
+  (i.e. top-level), following the spec at
+  :ref:`  index-hosted-attestations`.
+
+
+``packages.attestation-identities.kind``
+''''''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`  provenance-object`
+- The unique identity of the Trusted Publisher.
+
+
+``[packages.tool]``
+-------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- Similar usage as that of the ``[tool]`` table from the
+  :ref:`  pyproject-toml-spec`, but at the package version level instead
+  of at the lock file level (which is also available via ``[tool]``).
+- Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
+  installation).
+
+
+``[tool]``
+==========
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- See ``packages.tool``.
+
+
+-------
+Example
+-------
+
+.. code-block:: TOML
+
+  lock-version = '1.0'
+  environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
+  requires-python = '==3.12'
+  created-by = 'mousebender'
+
+  [[packages]]
+  name = 'attrs'
+  version = '25.1.0'
+  requires-python = '>=3.8'
+  wheels = [
+    {name = 'attrs-25.1.0-py3-none-any.whl', upload-time = 2025-01-25T11:30:10.164985+00:00, url = 'https://files.pythonhosted.org/packages/fc/30/d4986a882011f9df997a55e6becd864812ccfcd821d64aac8570ee39f719/attrs-25.1.0-py3-none-any.whl', size = 63152, hashes = {sha256 = 'c75a69e28a550a7e93789579c22aa26b0f5b83b75dc4e08fe092980051e1090a'}},
+  ]
+  [[packages.attestation-identities]]
+  environment = 'release-pypi'
+  kind = 'GitHub'
+  repository = 'python-attrs/attrs'
+  workflow = 'pypi-package.yml'
+
+  [[packages]]
+  name = 'cattrs'
+  version = '24.1.2'
+  requires-python = '>=3.8'
+  dependencies = [
+      {name = 'attrs'},
+  ]
+  wheels = [
+    {name = 'cattrs-24.1.2-py3-none-any.whl', upload-time = 2024-09-22T14:58:34.812643+00:00, url = 'https://files.pythonhosted.org/packages/c8/d5/867e75361fc45f6de75fe277dd085627a9db5ebb511a87f27dc1396b5351/cattrs-24.1.2-py3-none-any.whl', size = 66446, hashes = {sha256 = '67c7495b760168d931a10233f979b28dc04daf853b30752246f4f8471c6d68d0'}},
+  ]
+
+  [[packages]]
+  name = 'numpy'
+  version = '2.2.3'
+  requires-python = '>=3.10'
+  wheels = [
+    {name = 'numpy-2.2.3-cp312-cp312-win_amd64.whl', upload-time = 2025-02-13T16:51:21.821880+00:00, url = 'https://files.pythonhosted.org/packages/42/6e/55580a538116d16ae7c9aa17d4edd56e83f42126cb1dfe7a684da7925d2c/numpy-2.2.3-cp312-cp312-win_amd64.whl', size = 12626357, hashes = {sha256 = '83807d445817326b4bcdaaaf8e8e9f1753da04341eceec705c001ff342002e5d'}},
+    {name = 'numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', upload-time = 2025-02-13T16:50:00.079662+00:00, url = 'https://files.pythonhosted.org/packages/39/04/78d2e7402fb479d893953fb78fa7045f7deb635ec095b6b4f0260223091a/numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', size = 16116679, hashes = {sha256 = '3b787adbf04b0db1967798dba8da1af07e387908ed1553a0d6e74c084d1ceafe'}},
+  ]
+
+  [tool.mousebender]
+  command = ['.', 'lock', '--platform', 'cpython3.12-windows-x64', '--platform', 'cpython3.12-manylinux2014-x64', 'cattrs', 'numpy']
+  run-on = 2025-03-06T12:28:57.760769
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: We could then lint it even. Although, we could also plug linters for RST code blocks too: (https://github.com/ansible/awx-plugins/pull/99/files#diff-85933aa74a2d66c3e4dcdf7a9ad8397f5a7971080d34ef1108296a7c6b69e7e3R141-R144).
created_at: 2025-04-16T13:32:53Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,892 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-directory-path:
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+.. _pylock-packages-directory-editable:
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+.. _pylock-packages-directory-subdirectory:
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-archive:
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-archive-url:
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-url`.
+
+
+.. _pylock-packages-archive-path:
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-path`.
+
+
+.. _pylock-packages-archive-size:
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+.. _pylock-packages-archive-upload-time:
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+.. _pylock-packages-archive-hashes:
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+.. _pylock-packages-archive-subdirectory:
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-index:
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+.. _pylock-packages-sdist:
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+.. _pylock-packages-sdist-name:
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of
+  :ref:`pylock-packages-sdist-path`/ :ref:`pylock-packages-sdist-url` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+.. _pylock-packages-sdist-upload-time:
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-upload-time`.
+
+
+.. _pylock-packages-sdist-url:
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-url`.
+
+
+.. _pylock-packages-sdist-path:
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-path`.
+
+
+.. _pylock-packages-sdist-size:
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-size`.
+
+
+.. _pylock-packages-sdist-hashes:
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-hashes`.
+
+
+
+.. _pylock-packages-wheels:
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+.. _pylock-packages-wheels-name:
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of
+  :ref:`pylock-packages-wheels-path`/ :ref:`pylock-packages-wheels-url` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`binary-distribution-format` file.
+
+
+.. _pylock-packages-wheels-upload-time:
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-upload-time`.
+
+
+.. _pylock-packages-wheels-url:
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-url`.
+
+
+.. _pylock-packages-wheels-path:
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-path`.
+
+
+.. _pylock-packages-wheels-size:
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-size`.
+
+
+.. _pylock-packages-wheels-hashes:
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-hashes`.
+
+
+.. _pylock-packages-attestation-identities:
+
+``[[packages.attestation-identities]]``
+---------------------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: :ref:`  provenance-object`
+- A recording of the attestations for **any** file recorded for this package.
+- If available, tools SHOULD include the attestation identities found.
+- Publisher-specific keys are to be included in the table as-is
+  (i.e. top-level), following the spec at
+  :ref:`  index-hosted-attestations`.
+
+
+.. _pylock-packages-attestation-identities-kind:
+
+``packages.attestation-identities.kind``
+''''''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`  provenance-object`
+- The unique identity of the Trusted Publisher.
+
+
+.. _pylock-packages-tool:
+
+``[packages.tool]``
+-------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- Similar usage as that of the :ref:`pylock-tool` table from the
+  :ref:`  pyproject-toml-spec`, but at the package version level instead
+  of at the lock file level (which is also available via :ref:`pylock-tool`).
+- Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
+  installation).
+
+
+.. _pylock-tool:
+
+``[tool]``
+==========
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`pyproject-tool-table`
+- See :ref:`pylock-packages-tool`.
+
+
+-------
+Example
+-------
+
+.. code-block:: TOML
+
+  lock-version = '1.0'
+  environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
+  requires-python = '==3.12'
+  created-by = 'mousebender'
+
+  [[packages]]
+  name = 'attrs'
+  version = '25.1.0'
+  requires-python = '>=3.8'
+  wheels = [
+    {name = 'attrs-25.1.0-py3-none-any.whl', upload-time = 2025-01-25T11:30:10.164985+00:00, url = 'https://files.pythonhosted.org/packages/fc/30/d4986a882011f9df997a55e6becd864812ccfcd821d64aac8570ee39f719/attrs-25.1.0-py3-none-any.whl', size = 63152, hashes = {sha256 = 'c75a69e28a550a7e93789579c22aa26b0f5b83b75dc4e08fe092980051e1090a'}},
+  ]
+  [[packages.attestation-identities]]
+  environment = 'release-pypi'
+  kind = 'GitHub'
+  repository = 'python-attrs/attrs'
+  workflow = 'pypi-package.yml'
+
+  [[packages]]
+  name = 'cattrs'
+  version = '24.1.2'
+  requires-python = '>=3.8'
+  dependencies = [
+      {name = 'attrs'},
+  ]
+  wheels = [
+    {name = 'cattrs-24.1.2-py3-none-any.whl', upload-time = 2024-09-22T14:58:34.812643+00:00, url = 'https://files.pythonhosted.org/packages/c8/d5/867e75361fc45f6de75fe277dd085627a9db5ebb511a87f27dc1396b5351/cattrs-24.1.2-py3-none-any.whl', size = 66446, hashes = {sha256 = '67c7495b760168d931a10233f979b28dc04daf853b30752246f4f8471c6d68d0'}},
+  ]
+
+  [[packages]]
+  name = 'numpy'
+  version = '2.2.3'
+  requires-python = '>=3.10'
+  wheels = [
+    {name = 'numpy-2.2.3-cp312-cp312-win_amd64.whl', upload-time = 2025-02-13T16:51:21.821880+00:00, url = 'https://files.pythonhosted.org/packages/42/6e/55580a538116d16ae7c9aa17d4edd56e83f42126cb1dfe7a684da7925d2c/numpy-2.2.3-cp312-cp312-win_amd64.whl', size = 12626357, hashes = {sha256 = '83807d445817326b4bcdaaaf8e8e9f1753da04341eceec705c001ff342002e5d'}},
+    {name = 'numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', upload-time = 2025-02-13T16:50:00.079662+00:00, url = 'https://files.pythonhosted.org/packages/39/04/78d2e7402fb479d893953fb78fa7045f7deb635ec095b6b4f0260223091a/numpy-2.2.3-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl', size = 16116679, hashes = {sha256 = '3b787adbf04b0db1967798dba8da1af07e387908ed1553a0d6e74c084d1ceafe'}},
+  ]
+
+  [tool.mousebender]
+  command = ['.', 'lock', '--platform', 'cpython3.12-windows-x64', '--platform', 'cpython3.12-manylinux2014-x64', 'cattrs', 'numpy']
+  run-on = 2025-03-06T12:28:57.760769
+
+
+------------
+Installation
+------------
+
+The following outlines the steps to be taken to install from a lock file
+(while the requirements are prescriptive, the general steps and order are
+a suggestion):
+
+#. Gather the extras and dependency groups to install and set ``extras`` and
+   ``dependency_groups`` for marker evaluation, respectively.
+
+   #. ``extras`` SHOULD be set to the empty set by default.
+   #. ``dependency_groups`` SHOULD be the set created from
+      :ref:`pylock-default-groups` by default.
+
+#. Check if the metadata version specified by :ref:`pylock-lock-version` is
+   supported; an error or warning MUST be raised as appropriate.
+#. If :ref:`pylock-requires-python` is specified, check that the environment
+   being installed for meets the requirement; an error MUST be raised if it is
+   not met.
+#. If :ref:`pylock-environments` is specified, check that at least one of the
+   environment marker expressions is satisfied; an error MUST be raised if no
+   expression is satisfied.
+#. For each package listed in :ref:`pylock-packages`:
+
+   #. If :ref:`pylock-packages-marker` is specified, check if it is satisfied;
+      if it isn't, skip to the next package.
+   #. If :ref:`pylock-packages-requires-python` is specified, check if it is
+      satisfied; an error MUST be raised if it isn't.
+   #. Check that no other conflicting instance of the package has been slated to
+      be installed; an error about the ambiguity MUST be raised otherwise.
+   #. Check that the source of the package is specified appropriately (i.e.
+      there are no conflicting sources in the package entry);
+      an error MUST be raised if any issues are found.
+   #. Add the package to the set of packages to install.
+
+#. For each package to be installed:
+
+   - If :ref:`pylock-packages-vcs` is set:
+
+     #. Clone the repository to the commit ID specified in
+        :ref:`pylock-packages-vcs-commit-id`.
+     #. :ref:`Build <source-distribution-format-source-tree>` the package,
+        respecting :ref:`pylock-packages-vcs-subdirectory`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if :ref:`pylock-packages-directory` is set:
+
+     #. :ref:`Build <source-distribution-format-source-tree>` the package,
+        respecting :ref:`pylock-packages-directory-subdirectory`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if :ref:`pylock-packages-archive` is set:
+
+     #. Get the file.
+     #. Validate using :ref:`pylock-packages-archive-size` and
+        :ref:`pylock-packages-archive-hashes`.
+     #. :ref:`Build <source-distribution-format-source-tree>` the package,
+        respecting :ref:`pylock-packages-archive-subdirectory`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if there are entries for :ref:`pylock-packages-wheels`:
+
+     #. Look for the appropriate wheel file based on
+        :ref:`pylock-packages-wheels-name`; if one is not found then move on to
+        :ref:`pylock-packages-sdist` or an error MUST be raised about a
+        lack of source for the project.
+     #. Get the file:
+
+        - If :ref:`pylock-packages-wheels-path` is set, use it.
+        - Else if :ref:`pylock-packages-wheels-url` is set, try to use it;
+          optionally tools MAY use :ref:`pylock-packages-index` or some
+          tool-specific mechanism to download the selected wheel file (tools
+          MUST NOT try to change what wheel file to download based on what's
+          available; what file to install should be determined in an offline
+          fashion for reproducibility).
+
+     #. Validate using :ref:`pylock-packages-wheels-size` and
+        :ref:`pylock-packages-wheels-hashes`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if no :ref:`pylock-packages-wheels` file is found or
+     :ref:`pylock-packages-sdist` is solely set:
+
+     #. Get the file.
+
+        - If :ref:`pylock-packages-sdist-path` is set, use it.
+        - Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools
+          MAY use :ref:`pylock-packages-index` or some tool-specific mechanism
+          to download the file.
+
+     #. Validate using :ref:`pylock-packages-sdist-size` and
+        :ref:`pylock-packages-sdist-hashes`.
+     #. :ref:`Build <source-distribution-format-sdist>` the package.
+     #. :ref:`Install <binary-distribution-format>`.
+
+
+-------
+History
+-------
+
+- April 2025: Initial version, approved via :pep:`751`.
+
+
+.. _Content-Length: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Length
+.. _Dependabot: https://docs.github.com/en/code-security/dependabot
+.. _HEAD: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD
+.. _PDM: https://pypi.org/project/pdm/
+.. _pip-tools: https://pypi.org/project/pip-tools/
path: source/specifications/pylock-toml.rst
user: login: brettcannon
body: Nope. I can normalize to PyPI.
created_at: 2025-04-16T17:57:25Z
author_association: MEMBER
diff_hunk: @@ -235,52 +236,80 @@ no current specification for this. Regardless, outside of a context where this
 special handling is taking place, the "extra" variable should result in an
 error like all other unknown variables.
 
+The "extras" and "dependency_groups" variables are also special. They are used
+to specify any requested extras or dependency groups when installing from a lock
+file. Outside of the context of lock files, these two variables should result in
+an error like all other unknown variables.
+
 .. list-table::
    :header-rows: 1
 
    * - Marker
      - Python equivalent
+     - Type
      - Sample values
    * - ``os_name``
      - :py:data:`os.name`
+     - String
      - ``posix``, ``java``
    * - ``sys_platform``
      - :py:data:`sys.platform`
+     - String
      - ``linux``, ``linux2``, ``darwin``, ``java1.8.0_51`` (note that "linux"
        is from Python3 and "linux2" from Python2)
    * - ``platform_machine``
      - :py:func:`platform.machine()`
+     - String
      - ``x86_64``
    * - ``platform_python_implementation``
      - :py:func:`platform.python_implementation()`
+     - String
      - ``CPython``, ``Jython``
    * - ``platform_release``
      - :py:func:`platform.release()`
+     - String
      - ``3.14.1-x86_64-linode39``, ``14.5.0``, ``1.8.0_51``
    * - ``platform_system``
      - :py:func:`platform.system()`
+     - String
      - ``Linux``, ``Windows``, ``Java``
    * - ``platform_version``
      - :py:func:`platform.version()`
+     - String
      - ``#1 SMP Fri Apr 25 13:07:35 EDT 2014``
        ``Java HotSpot(TM) 64-Bit Server VM, 25.51-b03, Oracle Corporation``
        ``Darwin Kernel Version 14.5.0: Wed Jul 29 02:18:53 PDT 2015; root:xnu-2782.40.9~2/RELEASE_X86_64``
    * - ``python_version``
      - ``'.'.join(platform.python_version_tuple()[:2])``
+     - :ref:`Version <version-specifiers>`
      - ``3.4``, ``2.7``
    * - ``python_full_version``
      - :py:func:`platform.python_version()`
+     - :ref:`Version <version-specifiers>`
      - ``3.4.0``, ``3.5.0b1``
    * - ``implementation_name``
      - :py:data:`sys.implementation.name <sys.implementation>`
+     - String
      - ``cpython``
    * - ``implementation_version``
      - see definition below
+     - :ref:`Version <version-specifiers>`
      - ``3.4.0``, ``3.5.0b1``
    * - ``extra``
      - An error except when defined by the context interpreting the
        specification.
+     - String
      - ``test``
+   * - ``extras``
+     - An error except when defined by the context interpreting the
+       specification.
+     - Set of strings
+     - ``{"test"}``
path: source/specifications/dependency-specifiers.rst
user: login: webknjaz
body: Perhaps, it'd be better to use different examples for extras and dependency groups? I think it's good idea to show a "test" dependency group but something like "toml" as an extra. The reason is that I feel like using the same names might contribute to the use-case confusion that already exists when people think about dependencies and using the same example basically hints that these are semantically the same while they aren't.
created_at: 2025-05-02T15:18:47Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,60 @@
+lock-version = '1.0'
+environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
+requires-python = '==3.12'
+created-by = 'mousebender'
+
+[[packages]]
+name = 'attrs'
+version = '25.1.0'
+requires-python = '>=3.8'
path: source/specifications/pylock-toml/pylock.example.toml
user: login: webknjaz
body: Not sure if in scope but I've been trying to use sparse style across PyPUG. Do you think the generator can be updated to produce something like this?
```suggestion
requires-python = '>= 3.8'
```

I see that it's already sparse in extras / environments.
created_at: 2025-05-02T16:27:05Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-directory-path:
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+.. _pylock-packages-directory-editable:
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
'''''''''''''''''''''''''''''''
```

created_at: 2025-05-02T17:08:46Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+-------------------------
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
------------------------
```

created_at: 2025-05-02T17:09:04Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+-------------------------
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
------------------------
```

created_at: 2025-05-02T17:09:13Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
'''''''''''''''''''''''''''''
```

created_at: 2025-05-02T17:09:23Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
''''''''''''''''''''''''''
```

created_at: 2025-05-02T17:09:33Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
'''''''''''''''''''''''''''''''''''
```

created_at: 2025-05-02T17:09:41Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
'''''''''''''''''''''
```

created_at: 2025-05-02T17:09:50Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
''''''''''''''''''''
```

created_at: 2025-05-02T17:09:59Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
'''''''''''''''''''''
```

created_at: 2025-05-02T17:10:07Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
------------------
```

created_at: 2025-05-02T17:10:16Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-directory-path:
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+.. _pylock-packages-directory-editable:
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+.. _pylock-packages-directory-subdirectory:
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
'''''''''''''''''''''''''''''''''''
```

created_at: 2025-05-02T17:12:15Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-directory-path:
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
'''''''''''''''''''''''''''
```

created_at: 2025-05-02T17:12:35Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
2. A multi-use :file:`pylock.toml` with a dependency group with the name of the service
```
created_at: 2025-05-02T17:14:25Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
3. The default install of :file:`pylock.toml`
```
created_at: 2025-05-02T17:14:40Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
:file:`pylock.spam.toml` to install from, and if that file didn't exist then install
```
created_at: 2025-05-02T17:15:00Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
from :file:`pylock.toml` and look for a dependency group named "spam" to use if
```
created_at: 2025-05-02T17:15:21Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
of the lock file. Locking against a single :file:`pyproject.toml`, for instance,
```
created_at: 2025-05-02T17:15:43Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
would place the :file:`pylock.toml` in the same directory. If the lock file covered
```
created_at: 2025-05-02T17:15:59Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
multiple projects in a monorepo, then the expectation is the :file:`pylock.toml`
```
created_at: 2025-05-02T17:16:14Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: Not sure if it makes sense to refer to this document as a PEP.
```suggestion
recorded in a consistent order (if inspiration is desired, this specification has tried to
```
created_at: 2025-05-02T17:17:43Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: Is this meant to be a comment?
created_at: 2025-05-02T17:18:29Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-directory-path:
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+.. _pylock-packages-directory-editable:
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+.. _pylock-packages-directory-subdirectory:
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-archive:
+
+``[packages.archive]``
+-----------------------
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
----------------------
```
created_at: 2025-05-02T17:20:30Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-directory-path:
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+.. _pylock-packages-directory-editable:
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+.. _pylock-packages-directory-subdirectory:
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-archive:
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-archive-url:
+
+``packages.archive.url``
+'''''''''''''''''''''''''
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
''''''''''''''''''''''''
```
created_at: 2025-05-02T17:20:38Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-directory-path:
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+.. _pylock-packages-directory-editable:
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+.. _pylock-packages-directory-subdirectory:
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-archive:
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-archive-url:
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-url`.
+
+
+.. _pylock-packages-archive-path:
+
+``packages.archive.path``
+''''''''''''''''''''''''''
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
'''''''''''''''''''''''''
```
created_at: 2025-05-02T17:20:47Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-directory-path:
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+.. _pylock-packages-directory-editable:
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+.. _pylock-packages-directory-subdirectory:
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-archive:
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-archive-url:
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-url`.
+
+
+.. _pylock-packages-archive-path:
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-path`.
+
+
+.. _pylock-packages-archive-size:
+
+``packages.archive.size``
+''''''''''''''''''''''''''
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
'''''''''''''''''''''''''
```
created_at: 2025-05-02T17:21:03Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-directory-path:
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+.. _pylock-packages-directory-editable:
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+.. _pylock-packages-directory-subdirectory:
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-archive:
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-archive-url:
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-url`.
+
+
+.. _pylock-packages-archive-path:
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-path`.
+
+
+.. _pylock-packages-archive-size:
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+.. _pylock-packages-archive-upload-time:
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+.. _pylock-packages-archive-hashes:
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
'''''''''''''''''''''''''''''
```
created_at: 2025-05-02T17:21:27Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-directory-path:
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+.. _pylock-packages-directory-editable:
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+.. _pylock-packages-directory-subdirectory:
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-archive:
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-archive-url:
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-url`.
+
+
+.. _pylock-packages-archive-path:
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-path`.
+
+
+.. _pylock-packages-archive-size:
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+.. _pylock-packages-archive-upload-time:
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+.. _pylock-packages-archive-hashes:
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+.. _pylock-packages-archive-subdirectory:
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
'''''''''''''''''''''''''''''''''
```
created_at: 2025-05-02T17:21:41Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-directory-path:
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+.. _pylock-packages-directory-editable:
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+.. _pylock-packages-directory-subdirectory:
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-archive:
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-archive-url:
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-url`.
+
+
+.. _pylock-packages-archive-path:
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-path`.
+
+
+.. _pylock-packages-archive-size:
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+.. _pylock-packages-archive-upload-time:
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+.. _pylock-packages-archive-hashes:
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+.. _pylock-packages-archive-subdirectory:
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-index:
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+.. _pylock-packages-sdist:
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+.. _pylock-packages-sdist-name:
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of
+  :ref:`pylock-packages-sdist-path`/ :ref:`pylock-packages-sdist-url` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+.. _pylock-packages-sdist-upload-time:
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-upload-time`.
+
+
+.. _pylock-packages-sdist-url:
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-url`.
+
+
+.. _pylock-packages-sdist-path:
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-path`.
+
+
+.. _pylock-packages-sdist-size:
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-size`.
+
+
+.. _pylock-packages-sdist-hashes:
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-hashes`.
+
+
+
+.. _pylock-packages-wheels:
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
+- Tools MUST support wheel files, both from a locking and installation
+  perspective.
+
+
+.. _pylock-packages-wheels-name:
+
+``packages.wheels.name``
+''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of
+  :ref:`pylock-packages-wheels-path`/ :ref:`pylock-packages-wheels-url` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`binary-distribution-format` file.
+
+
+.. _pylock-packages-wheels-upload-time:
+
+``packages.wheels.upload-time``
+'''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-upload-time`.
+
+
+.. _pylock-packages-wheels-url:
+
+``packages.wheels.url``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-url`.
+
+
+.. _pylock-packages-wheels-path:
+
+``packages.wheels.path``
+''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-path`.
+
+
+.. _pylock-packages-wheels-size:
+
+``packages.wheels.size``
+''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-size`.
+
+
+.. _pylock-packages-wheels-hashes:
+
+``packages.wheels.hashes``
+''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-hashes`.
+
+
+.. _pylock-packages-attestation-identities:
+
+``[[packages.attestation-identities]]``
+---------------------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: :ref:`  provenance-object`
+- A recording of the attestations for **any** file recorded for this package.
+- If available, tools SHOULD include the attestation identities found.
+- Publisher-specific keys are to be included in the table as-is
+  (i.e. top-level), following the spec at
+  :ref:`  index-hosted-attestations`.
+
+
+.. _pylock-packages-attestation-identities-kind:
+
+``packages.attestation-identities.kind``
+''''''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`  provenance-object`
+- The unique identity of the Trusted Publisher.
+
+
+.. _pylock-packages-tool:
+
+``[packages.tool]``
+-------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`  pyproject-tool-table`
+- Similar usage as that of the :ref:`pylock-tool` table from the
+  :ref:`  pyproject-toml-spec`, but at the package version level instead
+  of at the lock file level (which is also available via :ref:`pylock-tool`).
+- Data recorded in the table MUST be disposable (i.e. it MUST NOT affect
+  installation).
+
+
+.. _pylock-tool:
+
+``[tool]``
+==========
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`pyproject-tool-table`
+- See :ref:`pylock-packages-tool`.
+
+
+-------
+Example
+-------
+
+.. literalinclude:: pylock-toml/pylock.example.toml
+
+
+------------
+Installation
+------------
+
+The following outlines the steps to be taken to install from a lock file
+(while the requirements are prescriptive, the general steps and order are
+a suggestion):
+
+#. Gather the extras and dependency groups to install and set ``extras`` and
+   ``dependency_groups`` for marker evaluation, respectively.
+
+   #. ``extras`` SHOULD be set to the empty set by default.
+   #. ``dependency_groups`` SHOULD be the set created from
+      :ref:`pylock-default-groups` by default.
+
+#. Check if the metadata version specified by :ref:`pylock-lock-version` is
+   supported; an error or warning MUST be raised as appropriate.
+#. If :ref:`pylock-requires-python` is specified, check that the environment
+   being installed for meets the requirement; an error MUST be raised if it is
+   not met.
+#. If :ref:`pylock-environments` is specified, check that at least one of the
+   environment marker expressions is satisfied; an error MUST be raised if no
+   expression is satisfied.
+#. For each package listed in :ref:`pylock-packages`:
+
+   #. If :ref:`pylock-packages-marker` is specified, check if it is satisfied;
+      if it isn't, skip to the next package.
+   #. If :ref:`pylock-packages-requires-python` is specified, check if it is
+      satisfied; an error MUST be raised if it isn't.
+   #. Check that no other conflicting instance of the package has been slated to
+      be installed; an error about the ambiguity MUST be raised otherwise.
+   #. Check that the source of the package is specified appropriately (i.e.
+      there are no conflicting sources in the package entry);
+      an error MUST be raised if any issues are found.
+   #. Add the package to the set of packages to install.
+
+#. For each package to be installed:
+
+   - If :ref:`pylock-packages-vcs` is set:
+
+     #. Clone the repository to the commit ID specified in
+        :ref:`pylock-packages-vcs-commit-id`.
+     #. :ref:`Build <source-distribution-format-source-tree>` the package,
+        respecting :ref:`pylock-packages-vcs-subdirectory`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if :ref:`pylock-packages-directory` is set:
+
+     #. :ref:`Build <source-distribution-format-source-tree>` the package,
+        respecting :ref:`pylock-packages-directory-subdirectory`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if :ref:`pylock-packages-archive` is set:
+
+     #. Get the file.
+     #. Validate using :ref:`pylock-packages-archive-size` and
+        :ref:`pylock-packages-archive-hashes`.
+     #. :ref:`Build <source-distribution-format-source-tree>` the package,
+        respecting :ref:`pylock-packages-archive-subdirectory`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if there are entries for :ref:`pylock-packages-wheels`:
+
+     #. Look for the appropriate wheel file based on
+        :ref:`pylock-packages-wheels-name`; if one is not found then move on to
+        :ref:`pylock-packages-sdist` or an error MUST be raised about a
+        lack of source for the project.
+     #. Get the file:
+
+        - If :ref:`pylock-packages-wheels-path` is set, use it.
+        - Else if :ref:`pylock-packages-wheels-url` is set, try to use it;
+          optionally tools MAY use :ref:`pylock-packages-index` or some
+          tool-specific mechanism to download the selected wheel file (tools
+          MUST NOT try to change what wheel file to download based on what's
+          available; what file to install should be determined in an offline
+          fashion for reproducibility).
+
+     #. Validate using :ref:`pylock-packages-wheels-size` and
+        :ref:`pylock-packages-wheels-hashes`.
+     #. :ref:`Install <binary-distribution-format>`.
+
+   - Else if no :ref:`pylock-packages-wheels` file is found or
+     :ref:`pylock-packages-sdist` is solely set:
+
+     #. Get the file.
+
+        - If :ref:`pylock-packages-sdist-path` is set, use it.
+        - Else if :ref:`pylock-packages-sdist-url` is set, try to use it; tools
+          MAY use :ref:`pylock-packages-index` or some tool-specific mechanism
+          to download the file.
+
+     #. Validate using :ref:`pylock-packages-sdist-size` and
+        :ref:`pylock-packages-sdist-hashes`.
+     #. :ref:`Build <source-distribution-format-sdist>` the package.
+     #. :ref:`Install <binary-distribution-format>`.
+
+
+-------
+History
+-------
+
+- April 2025: Initial version, approved via :pep:`751`.
+
+
+.. _Content-Length: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Length
+.. _Dependabot: https://docs.github.com/en/code-security/dependabot
+.. _HEAD: https://developer.mozilla.org/en-US/docs/Web/HTTP/Methods/HEAD
+.. _PDM: https://pypi.org/project/pdm/
+.. _pip-tools: https://pypi.org/project/pip-tools/
+.. _Poetry: https://pypi.org/project/poetry/
+.. _requirements file:
+.. _requirements files: https://pip.pypa.io/en/stable/reference/requirements-file-format/
+.. _software bill of materials: https://www.cisa.gov/sbom
+.. _TOML: https://toml.io/
+.. _uv: https://pypi.org/project/uv/
+.. _URL: https://url.spec.whatwg.org/
+.. _URL: https://url.spec.whatwg.org/
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
.. _URL: https://url.spec.whatwg.org/
```

created_at: 2025-05-02T17:24:59Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
+
+.. _pylock-lock-version:
+
+``lock-version``
+================
+
+- **Type**: string; value of ``"1.0"``
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-metadata-version`
+- 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 a tool supports the major version but not the minor version, a tool
+  SHOULD warn when an unknown key is seen.
+- If a tool doesn't support a major version, it MUST raise an error.
+
+
+.. _pylock-environments:
+
+``environments``
+================
+
+- **Type**: Array of strings
+- **Required?**: no
+- **Inspiration**: uv_
+- A list of :ref:`dependency-specifiers-environment-markers` for
+  which the lock file is considered compatible with.
+- Tools SHOULD write exclusive/non-overlapping environment markers to ease in
+  understanding.
+
+
+.. _pylock-requires-python:
+
+``requires-python``
+===================
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Specifies the :ref:`core-metadata-requires-python` for the minimum
+  Python version compatible for any environment supported by the lock file
+  (i.e. the minimum viable Python version for the lock file).
+
+
+.. _pylock-extras:
+
+``extras``
+==========
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`core-metadata-provides-extra`
+- The list of :ref:`extras <core-metadata-provides-extra>` supported
+  by this lock file.
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting extras MUST also support dependency groups.
+- Tools should explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no extras (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[project.optional-dependencies] <pyproject-toml-optional-dependencies>`
+  table), signalling that the lock file is, in effect, multi-use even if it only
+  looks to be single-use.
+
+
+.. _pylock-dependency-groups:
+
+``dependency-groups``
+=====================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: :ref:`pyproject-tool-table`
+- The list of :ref:`dependency-groups` publicly supported by this lock
+  file (i.e. dependency groups users are expected to be able to specify via a
+  tool's UI).
+- Lockers MAY choose to not support writing lock files that support extras and
+  dependency groups (i.e. tools may only support exporting a single-use lock
+  file).
+- Tools supporting dependency groups MUST also support extras.
+- Tools SHOULD explicitly set this key to an empty array to signal that the
+  inputs used to generate the lock file had no dependency groups (e.g. a
+  :ref:`pyproject.toml <pyproject-toml-spec>` file had no
+  :ref:`[dependency-groups] <dependency-groups>` table), signalling that the
+  lock file is, in effect, multi-use even if it only looks to be single-use.
+
+
+.. _pylock-default-groups:
+
+``default-groups``
+==================
+
+- **Type**: Array of strings
+- **Required?**: no; defaults to ``[]``
+- **Inspiration**: Poetry_, PDM_
+- The name of synthetic dependency groups to represent what should be installed
+  by default (e.g. what
+  :ref:`[project.dependencies] <pyproject-toml-dependencies>` implicitly
+  represents).
+- Meant to be used in situations where :ref:`pylock-packages-marker`
+  necessitates such a group to exist.
+- The groups listed by this key SHOULD NOT be listed in
+  :ref:`pylock-dependency-groups` as the groups are not meant to be directly
+  exposed to users by name but instead via an installer's UI.
+
+
+.. _pylock-created-by:
+
+``created-by``
+==============
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: Tools with their name in their lock file name
+- Records the name of the tool used to create the lock file.
+- Tools MAY use the :ref:`pylock-tool` table to record enough details that it
+  can be inferred what inputs were used to create the lock file.
+- Tools SHOULD record the normalized name of the tool if it is available as a
+  Python package to facilitate finding the tool.
+
+
+.. _pylock-packages:
+
+``[[packages]]``
+================
+
+- **Type**: array of tables
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_
+- 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.
+
+
+.. Identification
+
+.. _pylock-packages-name:
+
+``packages.name``
+-----------------
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`core-metadata-name`
+- The name of the package :ref:`normalized <name-normalization>`.
+
+
+.. _pylock-packages-version:
+
+``packages.version``
+--------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-version`
+- The version of the package.
+- The version SHOULD be specified when the version is known to be stable
+  (i.e. when an :ref:`sdist <source-distribution-format>` or
+  :ref:`wheels <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:`source tree <source-distribution-format-source-tree>` is used).
+
+
+.. Requirements
+
+.. _pylock-packages-marker:
+
+``packages.marker``
+-------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: PDM_
+- The
+  :ref:`environment marker <dependency-specifiers-environment-markers>`
+  which specify when the package should be installed.
+
+
+.. _pylock-packages-requires-python:
+
+``packages.requires-python``
+----------------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`core-metadata-requires-python`
+- Holds the :ref:`version-specifiers` for Python version compatibility
+  for the package.
+
+
+.. _pylock-packages-dependencies:
+
+``[[packages.dependencies]]``
+-----------------------------
+
+- **Type**: array of tables
+- **Required?**: no
+- **Inspiration**: PDM_, Poetry_, uv_
+- Records the other entries in :ref:`pylock-packages` which are direct
+  dependencies of this package.
+- Each entry is a table which contains the minimum information required to tell
+  which other package entry it corresponds to where doing a key-by-key
+  comparison would find the appropriate package with no ambiguity (e.g. if there
+  are two entries for the ``spam`` package, then you can include the version
+  number like ``{name = "spam", version = "1.0.0"}``, or by source like
+  ``{name = "spam", vcs = { url = "..."}``).
+- Tools MUST NOT use this information when doing installation; it is purely
+  informational for auditing purposes.
+
+
+.. Source
+
+.. _pylock-packages-vcs:
+
+``[packages.vcs]``
+-------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-directory`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure`
+- Record the version control system details for the
+  :ref:`source tree <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 MAY choose to only support a subset of the available VCS types.
+- Tools SHOULD provide a way for users to opt in/out of using version control
+  systems.
+- Installation from a version control system is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-vcs-type:
+
+``packages.vcs.type``
+''''''''''''''''''''''
+
+- **Type**: string; supported values specified in
+  :ref:`direct-url-data-structure-registered-vcs`
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The type of version control system used.
+
+
+.. _pylock-packages-vcs-url:
+
+``packages.vcs.url``
+'''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-path` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- The URL_ to the source tree.
+
+
+.. _pylock-packages-vcs-path:
+
+``packages.vcs.path``
+''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: if :ref:`pylock-packages-vcs-url` is not specified
+- **Inspiration**: :ref:`direct-url-data-structure-vcs`
+- 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 explicitly
+  for portability.
+
+
+.. _pylock-packages-vcs-requested-revision:
+
+``packages.vcs.requested-revision``
+''''''''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`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:`direct-url-data-structure`; it MUST NOT be used to checkout
+  the repository.
+
+
+.. _pylock-packages-vcs-commit-id:
+
+``packages.vcs.commit-id``
+'''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`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 a
+  commit-hash, it MUST be used as the commit ID in order to reference an
+  immutable version of the source code.
+
+
+.. _pylock-packages-vcs-subdirectory:
+
+``packages.vcs.subdirectory``
+''''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-subdirectories`
+- The subdirectory within the
+  :ref:`source tree <source-distribution-format-source-tree>` where
+  the project root of the project is (e.g. the location of the
+  :ref:`pyproject.toml <pyproject-toml-spec>` file).
+- The path MUST be relative to the root of the source tree structure.
+
+
+.. _pylock-packages-directory:
+
+``[packages.directory]``
+-------------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-archive`, :ref:`pylock-packages-sdist`, and
+  :ref:`pylock-packages-wheels`
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- Record the local directory details for the
+  :ref:`source tree <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 in/out of using local directories.
+- Installation from a directory is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-directory-path:
+
+``packages.directory.path``
+''''''''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: yes
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- The local directory where the source tree is.
+- If the path is relative it MUST be relative to the location of the lock file.
+- If the path is relative it MAY use POSIX-style path separators for
+  portability.
+
+
+.. _pylock-packages-directory-editable:
+
+``packages.directory.editable``
+''''''''''''''''''''''''''''''''
+
+- **Type**: boolean
+- **Required?**: no; defaults to ``false``
+- **Inspiration**: :ref:`direct-url-data-structure-local-directory`
+- A flag representing whether the source tree was an editable install at lock
+  time.
+- An installer MAY choose to ignore this flag if user actions or context would
+  make an editable install unnecessary or undesirable (e.g. a container image
+  that will not be mounted for development purposes but instead deployed to
+  production where it would be treated at read-only).
+
+
+.. _pylock-packages-directory-subdirectory:
+
+``packages.directory.subdirectory``
+''''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-archive:
+
+``[packages.archive]``
+-----------------------
+
+- **Type**: table
+- **Required?**: no
+- **Inspiration**: :ref:`direct-url-data-structure-archive`
+- A direct reference to an archive file to install from
+  (this can include wheels and sdists, as well as other archive formats
+  containing a source tree).
+- Tools MAY choose to not support archive files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using archive files.
+- Installation from an archive file is considered originating from a
+  :ref:`direct URL reference <direct-url>`.
+
+
+.. _pylock-packages-archive-url:
+
+``packages.archive.url``
+'''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-url`.
+
+
+.. _pylock-packages-archive-path:
+
+``packages.archive.path``
+''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-path`.
+
+
+.. _pylock-packages-archive-size:
+
+``packages.archive.size``
+''''''''''''''''''''''''''
+
+- **Type**: integer
+- **Required?**: no
+- **Inspiration**: uv_, :ref:`simple-repository-api`
+- The size of the archive file.
+- Tools SHOULD provide the file size when reasonably possible (e.g. the file
+  size is available via the Content-Length_ header from a HEAD_ HTTP request).
+
+
+.. _pylock-packages-archive-upload-time:
+
+``packages.archive.upload-time``
+''''''''''''''''''''''''''''''''
+
+- **Type**: datetime
+- **Required?**: no
+- **Inspiration**: :ref:`simple-repository-api`
+- The time the file was uploaded.
+- The date and time MUST be recorded in UTC.
+
+
+.. _pylock-packages-archive-hashes:
+
+``[packages.archive.hashes]``
+''''''''''''''''''''''''''''''
+
+- **Type**: Table of strings
+- **Required?**: yes
+- **Inspiration**: PDM_, Poetry_, uv_, :ref:`simple-repository-api`
+- A table listing known hash values of the file where the key is the hash
+  algorithm and the value is the hash value.
+- The table MUST contain at least one entry.
+- Hash algorithm keys SHOULD be lowercase.
+- At least one secure algorithm from :py:data:`hashlib.algorithms_guaranteed`
+  SHOULD always be included (at time of writing, sha256 specifically is
+  recommended.
+
+
+.. _pylock-packages-archive-subdirectory:
+
+``packages.archive.subdirectory``
+''''''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-vcs-subdirectory`.
+
+
+.. _pylock-packages-index:
+
+``packages.index``
+------------------
+
+- **Type**: string
+- **Required?**: no
+- **Inspiration**: uv_
+- The base URL for the package index from :ref:`simple-repository-api`
+  where the sdist and/or wheels were found (e.g. ``https://pypi.org/simple/``).
+- When possible, this SHOULD be specified to assist with generating
+  `software bill of materials`_ -- aka SBOMs -- and to assist in finding a file
+  if a URL ceases to be valid.
+- Tools MAY support installing from an index if the URL recorded for a specific
+  file is no longer valid (e.g. returns a 404 HTTP error code).
+
+
+.. _pylock-packages-sdist:
+
+``[packages.sdist]``
+--------------------
+
+- **Type**: table
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
+- **Inspiration**: uv_
+- Details of a :ref:`source-distribution-format-sdist` for the
+  package.
+- Tools MAY choose to not support sdist files, both from a locking
+  and/or installation perspective.
+- Tools SHOULD provide a way for users to opt in/out of using sdist files.
+
+
+.. _pylock-packages-sdist-name:
+
+``packages.sdist.name``
+'''''''''''''''''''''''
+
+- **Type**: string
+- **Required?**: no, not when the last component of
+  :ref:`pylock-packages-sdist-path`/ :ref:`pylock-packages-sdist-url` would be
+  the same value
+- **Inspiration**: PDM_, Poetry_, uv_
+- The file name of the :ref:`source-distribution-format-sdist` file.
+
+
+.. _pylock-packages-sdist-upload-time:
+
+``packages.sdist.upload-time``
+''''''''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-upload-time`.
+
+
+.. _pylock-packages-sdist-url:
+
+``packages.sdist.url``
+''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-url`.
+
+
+.. _pylock-packages-sdist-path:
+
+``packages.sdist.path``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-path`.
+
+
+.. _pylock-packages-sdist-size:
+
+``packages.sdist.size``
+'''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-size`.
+
+
+.. _pylock-packages-sdist-hashes:
+
+``packages.sdist.hashes``
+'''''''''''''''''''''''''
+
+See :ref:`pylock-packages-archive-hashes`.
+
+
+
+.. _pylock-packages-wheels:
+
+``[[packages.wheels]]``
+-----------------------
+
+- **Type**: array of tables
+- **Required?**: no; mutually-exclusive with :ref:`pylock-packages-vcs`,
+  :ref:`pylock-packages-directory`, and :ref:`pylock-packages-archive`
+- **Inspiration**: PDM_, Poetry_, uv_
+- For recording the wheel files as specified by
+  :ref:`  binary-distribution-format` for the package.
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: ```suggestion
  :ref:`binary-distribution-format` for the package.
```
created_at: 2025-05-02T17:26:20Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
path: source/specifications/pylock-toml.rst
user: login: brettcannon
body: Yep. I can drop them if you want; they just help me separate the settings thematically.
created_at: 2025-05-02T21:09:35Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,60 @@
+lock-version = '1.0'
+environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
+requires-python = '==3.12'
+created-by = 'mousebender'
+
+[[packages]]
+name = 'attrs'
+version = '25.1.0'
+requires-python = '>=3.8'
path: source/specifications/pylock-toml/pylock.example.toml
user: login: brettcannon
body: The difference is I generated the extras/environments expression while the requires-python comes from the metadata of project and through 'packaging'. I just went ahead and updated the file by hand.
created_at: 2025-05-02T23:12:08Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,60 @@
+lock-version = '1.0'
+environments = ["sys_platform == 'win32'", "sys_platform == 'linux'"]
+requires-python = '==3.12'
+created-by = 'mousebender'
+
+[[packages]]
+name = 'attrs'
+version = '25.1.0'
+requires-python = '>=3.8'
path: source/specifications/pylock-toml/pylock.example.toml
user: login: webknjaz
body: Ah, I didn't realize. I thought that mousebender was reformatting those.. Thanks for doing this!
created_at: 2025-05-02T23:42:49Z
author_association: MEMBER
diff_hunk: @@ -0,0 +1,850 @@
+.. _pylock-toml-spec:
+.. _lock-file-spec:
+
+=============================
+``pylock.toml`` Specification
+=============================
+
+The ``pylock.toml`` file format is for specifying dependencies to enable
+reproducible installation in a Python environment.
+
+.. note:: This specification was originally defined in :pep:`751`.
+
+
+---------
+File Name
+---------
+
+A lock file MUST be named :file:`pylock.toml` or match the regular expression
+``r"^pylock\.([^.]+)\.toml$"`` if a name for the lock file is desired or if
+multiple lock files exist (i.e. the regular expression
+``r"^pylock\.([^.]+\.)?toml$"`` for any file name). The prefix and suffix of a
+named file MUST be lowercase when possible, for easy detection and removal,
+e.g.:
+
+.. code-block:: Python
+
+  if len(filename) > 11 and filename.startswith("pylock.") and filename.endswith(".toml"):
+      name = filename.removeprefix("pylock.").removesuffix(".toml")
+
+The expectation is that services that automatically install from lock files will
+search for:
+
+1. The lock file with the service's name and doing the default install
+2. A multi-use ``pylock.toml`` with a dependency group with the name of the service
+3. The default install of ``pylock.toml``
+
+E.g. a cloud host service named "spam" would first look for
+``pylock.spam.toml`` to install from, and if that file didn't exist then install
+from ``pylock.toml`` and look for a dependency group named "spam" to use if
+present.
+
+The lock file(s) SHOULD be located in the directory as appropriate for the scope
+of the lock file. Locking against a single ``pyproject.toml``, for instance,
+would place the ``pylock.toml`` in the same directory. If the lock file covered
+multiple projects in a monorepo, then the expectation is the ``pylock.toml``
+file would be in the directory that held all the projects being locked.
+
+
+-----------
+File Format
+-----------
+
+The format of the file is TOML_.
+
+Tools SHOULD write their lock files in a consistent way to minimize noise in
+diff output. Keys in tables -- including the top-level table -- SHOULD be
+recorded in a consistent order (if inspiration is desired, this PEP has tried to
+write down keys in a logical order). As well, tools SHOULD sort arrays in
+consistent order. Usage of inline tables SHOULD also be kept consistent.
+
+.. File details
path: source/specifications/pylock-toml.rst
user: login: webknjaz
body: Oh, I just wasn't sure if this was broken/forgotten syntax to something else. That's why I wanted to double check.
created_at: 2025-05-02T23:46:38Z
author_association: MEMBER

PR comments:
user: login: brettcannon
created_at: 2025-04-15T20:45:26Z
body: @FFY00 thanks for all of the references! I had to insert blank lines and then I went through and replaced every place I could think of with a reference. 😁
author_association: MEMBER
user: login: webknjaz
created_at: 2025-04-16T13:27:32Z
body: It's weird that the linkcheck job gets stuck for 48 minutes while on `main` it takes like a minute...
author_association: MEMBER
user: login: brettcannon
created_at: 2025-04-16T20:36:58Z
body: @FFY00 I took your reformat idea to try and keep the HTML page from having so much horizontal scroll, but I also indenting subtables for ease of reading.
author_association: MEMBER
user: login: brettcannon
created_at: 2025-04-16T20:39:06Z
body: @webknjaz looks like adding that URL to the ignore list did the trick to make CI fast again! PTAL.
author_association: MEMBER
user: login: brettcannon
created_at: 2025-05-02T14:45:26Z
body: @webknjaz anything I can do to help merge this? Support is getting released in various tools, but they are all working from the PEP at the moment.
author_association: MEMBER
user: login: webknjaz
created_at: 2025-05-02T15:10:04Z
body: Hey, sorry. I never got to dedicating adequate amount of time to review this but since you got other approvals, I'll just skim through the patch and merge if there's nothing that stands out.
author_association: MEMBER
user: login: brettcannon
created_at: 2025-05-02T23:21:14Z
body: @webknjaz I think I addressed all your comments; PTAL.
author_association: MEMBER
user: login: nmorey7721
created_at: 2025-05-03T12:37:26Z
body: My account is being hacked and compromised 
author_association: NONE