Merge main, full === detection, local version tests

Author: notatallshaw

.readthedocs.yml

@@ -8,7 +8,7 @@ version: 2
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.13"
+    python: "3.14"
   commands:
     - asdf plugin add uv
     - asdf install uv latest

docs/conf.py

@@ -21,7 +21,6 @@
     "sphinx.ext.doctest",
     "sphinx.ext.extlinks",
     "sphinx.ext.intersphinx",
-    "sphinx_toolbox.more_autodoc.autotypeddict",
 ]
 
 # General information about the project.

docs/dependency_groups.rst

@@ -0,0 +1,77 @@
+Dependency Groups
+=================
+
+.. currentmodule:: packaging.dependency_groups
+
+Package data as defined in ``pyproject.toml`` may include lists of dependencies
+in named groups. This is described by the
+:ref:`dependency groups specification <pypug:dependency-groups>`, which defines
+the ``[dependency-groups]`` table.
+
+This module provides tools for resolving group names to lists of requirements,
+most notably expanding ``include-group`` directives.
+
+Usage
+-----
+
+Two primary interfaces are offered. An object-based one which caches results and
+provides ``Requirements`` as its results:
+
+.. doctest::
+
+    >>> from packaging.dependency_groups import DependencyGroupResolver
+    >>> coverage = ["coverage"]
+    >>> test = ["pytest", {"include-group": "coverage"}]
+    >>> # A resolver is defined on a mapping of group names to group data, as
+    >>> # you might get by loading the [dependency-groups] TOML table.
+    >>> resolver = DependencyGroupResolver({"test": test, "coverage": coverage})
+    >>> # resolvers support expanding group names to Requirements
+    >>> resolver.resolve("coverage")
+    (<Requirement('coverage')>,)
+    >>> resolver.resolve("test")
+    (<Requirement('pytest')>, <Requirement('coverage')>)
+    >>> # resolvers can also be used to lookup the dependency groups without
+    >>> # expanding includes
+    >>> resolver.lookup("test")
+    (<Requirement('pytest')>, DependencyGroupInclude('coverage'))
+
+And a simpler functional interface which responds with strings:
+
+.. doctest::
+
+    >>> from packaging.dependency_groups import resolve_dependency_groups
+    >>> coverage = ["coverage"]
+    >>> test = ["pytest", {"include-group": "coverage"}]
+    >>> groups = {"test": test, "coverage": coverage}
+    >>> resolve_dependency_groups(groups, "test")
+    ('pytest', 'coverage')
+
+Reference
+---------
+
+Functional Interface
+''''''''''''''''''''
+
+.. autofunction:: resolve_dependency_groups
+
+
+Object Model Interface
+''''''''''''''''''''''
+
+.. autoclass:: DependencyGroupInclude
+    :members:
+
+.. autoclass:: DependencyGroupResolver
+    :members:
+
+Exceptions
+''''''''''
+
+.. autoclass:: DuplicateGroupNames
+    :members:
+
+.. autoclass:: CyclicDependencyGroup
+    :members:
+
+.. autoclass:: InvalidDependencyGroupObject
+    :members:

docs/direct_url.rst

@@ -0,0 +1,77 @@
+Direct URLs
+===========
+
+.. currentmodule:: packaging.direct_url
+
+Parse and validate `direct_url.json files <https://packaging.python.org/en/latest/specifications/direct-url/>`_.
+
+Usage
+-----
+
+.. code-block:: python
+
+    import json
+    from pathlib import Path
+
+    from packaging.direct_url import ArchiveInfo, DirectUrl, DirInfo, VcsInfo
+
+    # A VCS direct URL
+    vcs_direct_url = DirectUrl(
+        url="https://git.example.com/repo.git",
+        vcs_info=VcsInfo(
+            vcs="git",
+            commit_id="2df7bdd8dfef7b879390b9fc4016f02af2f118d4",
+            requested_revision="1.1.0",
+        ),
+    )
+
+    # An archive direct URL
+    archive_direct_url = DirectUrl(
+        url="https://example.com/archive.tar.gz",
+        archive_info=ArchiveInfo(
+            hashes={
+                "sha256": "dc321a1c18a37b5438424ef3714524229dab5f4f78b297671359426fef51be6c"
+            }
+        ),
+    )
+
+    # A local editable direct URL
+    archive_direct_url = DirectUrl(
+        url="file:///home/project/example",
+        dir_info=DirInfo(
+            editable=True,
+        ),
+    )
+
+    # Serialization to JSON
+    Path("/tmp/direct_url.json").write_text(
+        json.dumps(vcs_direct_url.to_dict()), encoding="utf-8"
+    )
+
+    # Load from JSON. The resulting DirectUrl object is validated against the
+    # specification, else a DirectUrlalidationError is raised
+    direct_url = DirectUrl.from_dict(
+        json.loads(Path("/tmp/direct_url.json").read_text(encoding="utf-8"))
+    )
+
+    # You can validate a manually constructed DirectUrl class
+    vcs_direct_url.validate()
+
+
+Reference
+---------
+
+.. autoclass:: DirectUrl
+    :members: from_dict, to_dict, validate
+    :exclude-members: __init__, __new__
+
+.. class:: ArchiveInfo
+
+.. class:: DirInfo
+
+.. class:: VcsInfo
+
+The following exception may be raised by this module:
+
+.. autoexception:: DirectUrlValidationError
+    :exclude-members: __init__, __new__

docs/index.rst

@@ -31,6 +31,8 @@ The ``packaging`` library uses calendar-based versioning (``YY.N``).
     metadata
     tags
     pylock
+    direct_url
+    dependency_groups
     utils
 
 .. toctree::

docs/licenses.rst

@@ -12,41 +12,5 @@ as `defined in PEP 639 <https://peps.python.org/pep-0639/#spdx>`__.
 Reference
 ---------
 
-.. class:: NormalizedLicenseExpression
-
-    A :class:`typing.NewType` of :class:`str`, representing a normalized
-    License-Expression.
-
-
-.. exception:: InvalidLicenseExpression
-
-    Raised when a License-Expression is invalid.
-
-
-.. function:: canonicalize_license_expression(raw_license_expression)
-
-    This function takes a valid License-Expression, and returns the normalized form of it.
-
-    The return type is typed as :class:`NormalizedLicenseExpression`. This allows type
-    checkers to help require that a string has passed through this function
-    before use.
-
-    :param str raw_license_expression: The License-Expression to canonicalize.
-    :raises InvalidLicenseExpression: If the License-Expression is invalid due to an
-        invalid/unknown license identifier or invalid syntax.
-
-    .. doctest::
-
-        >>> from packaging.licenses import canonicalize_license_expression
-        >>> canonicalize_license_expression("mit")
-        'MIT'
-        >>> canonicalize_license_expression("mit and (apache-2.0 or bsd-2-clause)")
-        'MIT AND (Apache-2.0 OR BSD-2-Clause)'
-        >>> canonicalize_license_expression("(mit")
-        Traceback (most recent call last):
-          ...
-        InvalidLicenseExpression: Invalid license expression: '(mit'
-        >>> canonicalize_license_expression("Use-it-after-midnight")
-        Traceback (most recent call last):
-          ...
-        InvalidLicenseExpression: Unknown license: 'Use-it-after-midnight'
+.. automodule:: packaging.licenses
+   :members:

docs/metadata.rst

@@ -47,6 +47,7 @@ Low Level Interface
 
 .. autoclass:: packaging.metadata.RawMetadata
     :members:
+    :undoc-members:
 
 .. autofunction:: packaging.metadata.parse_email