Merge branch 'validate-vers' of github.com:jaimergp/packageurl-python; branch 'main' of github.com:package-url/packageurl-python into validate-vers

Author: jaimergp

CHANGELOG.rst

@@ -1,6 +1,24 @@
 Changelog
 =========
 
+0.17.1 (2025-06-06)
+-------------------
+
+- Define "pkg" as a PackageURL ``SCHEME`` class attribute.
+  https://github.com/package-url/packageurl-python/issues/184
+
+- Add support for Maven in ``purl2url``.
+  https://github.com/package-url/packageurl-python/issues/177
+
+0.17.0 (2025-06-04)
+-------------------
+
+- Fix qualifiers type annotations.
+  https://github.com/package-url/packageurl-python/issues/169
+
+- Fix parsing of names and namespaces with colons.
+  https://github.com/package-url/packageurl-python/issues/152
+
 0.16.0 (2024-10-22)
 -------------------
 

Makefile

@@ -66,7 +66,6 @@ valid:
 
 test:
 	@echo "-> Run the test suite"
-	${MANAGE} test --noinput
 	bin/py.test tests
 
 .PHONY: virtualenv conf dev clean isort black mypy valid test

setup.cfg

@@ -1,6 +1,6 @@
 [metadata]
 name = packageurl-python
-version = 0.16.0
+version = 0.17.1
 license = MIT
 description = A purl aka. Package URL parser and builder
 long_description = file:README.rst

src/packageurl/__init__.py

@@ -26,6 +26,7 @@
 
 import string
 from collections import namedtuple
+from collections.abc import Mapping
 from typing import TYPE_CHECKING
 from typing import Any
 from typing import Union
@@ -37,6 +38,7 @@
 if TYPE_CHECKING:
     from collections.abc import Callable
     from collections.abc import Iterable
+    from typing import ClassVar
 
     from typing_extensions import Literal
     from typing_extensions import Self
@@ -230,9 +232,12 @@ def normalize_qualifiers(
 
     if not encode:
         return qualifiers_map
+    return _qualifier_map_to_string(qualifiers_map) or None
 
-    qualifiers_list = [f"{key}={value}" for key, value in qualifiers_map.items()]
-    return "&".join(qualifiers_list) or None
+
+def _qualifier_map_to_string(qualifiers: dict[str, str]) -> str:
+    qualifiers_list = [f"{key}={value}" for key, value in qualifiers.items()]
+    return "&".join(qualifiers_list)
 
 
 def normalize_subpath(subpath: AnyStr | None, encode: bool | None = True) -> str | None:
@@ -319,6 +324,8 @@ class PackageURL(
     https://github.com/package-url/purl-spec
     """
 
+    SCHEME: ClassVar[str] = "pkg"
+
     type: str
     namespace: str | None
     name: str
@@ -400,7 +407,7 @@ def to_dict(self, encode: bool | None = False, empty: Any = None) -> dict[str, A
 
         return data
 
-    def to_string(self) -> str:
+    def to_string(self, encode: bool | None = True) -> str:
         """
         Return a purl string built from components.
         """
@@ -411,10 +418,10 @@ def to_string(self) -> str:
             self.version,
             self.qualifiers,
             self.subpath,
-            encode=True,
+            encode=encode,
         )
 
-        purl = ["pkg:", type, "/"]
+        purl = [self.SCHEME, ":", type, "/"]
 
         if namespace:
             purl.extend((namespace, "/"))
@@ -427,6 +434,8 @@ def to_string(self) -> str:
 
         if qualifiers:
             purl.append("?")
+            if isinstance(qualifiers, Mapping):
+                qualifiers = _qualifier_map_to_string(qualifiers)
             purl.append(qualifiers)
 
         if subpath:
@@ -445,8 +454,10 @@ def from_string(cls, purl: str) -> Self:
             raise ValueError("A purl string argument is required.")
 
         scheme, sep, remainder = purl.partition(":")
-        if not sep or scheme != "pkg":
-            raise ValueError(f'purl is missing the required "pkg" scheme component: {purl!r}.')
+        if not sep or scheme != cls.SCHEME:
+            raise ValueError(
+                f'purl is missing the required "{cls.SCHEME}" scheme component: {purl!r}.'
+            )
 
         # this strip '/, // and /// as possible in :// or :///
         remainder = remainder.strip().lstrip("/")

src/packageurl/contrib/purl2url.py

@@ -28,6 +28,8 @@
 from packageurl.contrib.route import NoRouteAvailable
 from packageurl.contrib.route import Router
 
+DEFAULT_MAVEN_REPOSITORY = "https://repo.maven.apache.org/maven2"
+
 
 def get_repo_download_url_by_package_type(
     type, namespace, name, version, archive_extension="tar.gz"
@@ -314,6 +316,24 @@ def build_cocoapods_repo_url(purl):
     return name and f"https://cocoapods.org/pods/{name}"
 
 
+@repo_router.route("pkg:maven/.*")
+def build_maven_repo_url(purl):
+    """
+    Return a Maven repo URL from the `purl` string.
+    """
+    purl_data = PackageURL.from_string(purl)
+    namespace = purl_data.namespace
+    name = purl_data.name
+    version = purl_data.version
+    qualifiers = purl_data.qualifiers
+
+    base_url = qualifiers.get("repository_url", DEFAULT_MAVEN_REPOSITORY)
+
+    if namespace and name and version:
+        namespace = namespace.replace(".", "/")
+        return f"{base_url}/{namespace}/{name}/{version}"
+
+
 # Download URLs:
 
 
@@ -365,6 +385,28 @@ def build_npm_download_url(purl):
         return f"{base_url}/{name}/-/{name}-{version}.tgz"
 
 
+@download_router.route("pkg:maven/.*")
+def build_maven_download_url(purl):
+    """
+    Return a maven download URL from the `purl` string.
+    """
+    purl_data = PackageURL.from_string(purl)
+
+    namespace = purl_data.namespace
+    name = purl_data.name
+    version = purl_data.version
+    qualifiers = purl_data.qualifiers
+
+    base_url = qualifiers.get("repository_url", DEFAULT_MAVEN_REPOSITORY)
+    maven_type = qualifiers.get("type", "jar")  # default to "jar"
+    classifier = qualifiers.get("classifier")
+
+    if namespace and name and version:
+        namespace = namespace.replace(".", "/")
+        classifier = f"-{classifier}" if classifier else ""
+        return f"{base_url}/{namespace}/{name}/{version}/{name}-{version}{classifier}.{maven_type}"
+
+
 @download_router.route("pkg:hackage/.*")
 def build_hackage_download_url(purl):
     """

tests/contrib/test_purl2url.py

@@ -68,6 +68,8 @@ def test_purl2url_get_repo_url():
         "pkg:golang/gopkg.in/ldap.v3@v3.1.0": "https://pkg.go.dev/gopkg.in/ldap.v3@v3.1.0",
         "pkg:cocoapods/AFNetworking@4.0.1": "https://cocoapods.org/pods/AFNetworking",
         "pkg:cocoapods/MapsIndoors@3.24.0": "https://cocoapods.org/pods/MapsIndoors",
+        "pkg:maven/org.apache.commons/commons-io@1.3.2": "https://repo.maven.apache.org/maven2/org/apache/commons/commons-io/1.3.2",
+        "pkg:maven/org.apache.commons/commons-io@1.3.2?repository_url=https://repo1.maven.org/maven2": "https://repo1.maven.org/maven2/org/apache/commons/commons-io/1.3.2",
     }
 
     for purl, url in purls_url.items():
@@ -92,6 +94,10 @@ def test_purl2url_get_download_url():
         "pkg:gitlab/tg1999/firebase@1a122122": "https://gitlab.com/tg1999/firebase/-/archive/1a122122/firebase-1a122122.tar.gz",
         "pkg:gitlab/tg1999/firebase@1a122122?version_prefix=v": "https://gitlab.com/tg1999/firebase/-/archive/v1a122122/firebase-v1a122122.tar.gz",
         "pkg:gitlab/hoppr/hoppr@v1.11.1-dev.2": "https://gitlab.com/hoppr/hoppr/-/archive/v1.11.1-dev.2/hoppr-v1.11.1-dev.2.tar.gz",
+        "pkg:maven/org.apache.commons/commons-io@1.3.2": "https://repo.maven.apache.org/maven2/org/apache/commons/commons-io/1.3.2/commons-io-1.3.2.jar",
+        "pkg:maven/org.apache.commons/commons-io@1.3.2?repository_url=https://repo1.maven.org/maven2": "https://repo1.maven.org/maven2/org/apache/commons/commons-io/1.3.2/commons-io-1.3.2.jar",
+        "pkg:maven/org.apache.commons/commons-io@1.3.2?type=pom": "https://repo.maven.apache.org/maven2/org/apache/commons/commons-io/1.3.2/commons-io-1.3.2.pom",
+        "pkg:maven/org.apache.commons/commons-math3@3.6.1?classifier=sources": "https://repo.maven.apache.org/maven2/org/apache/commons/commons-math3/3.6.1/commons-math3-3.6.1-sources.jar",
         # From `download_url` qualifier
         "pkg:github/yarnpkg/yarn@1.3.2?download_url=https://github.com/yarnpkg/yarn/releases/download/v1.3.2/yarn-v1.3.2.tar.gz&version_prefix=v": "https://github.com/yarnpkg/yarn/releases/download/v1.3.2/yarn-v1.3.2.tar.gz",
         "pkg:generic/lxc-master.tar.gz?download_url=https://salsa.debian.org/lxc-team/lxc/-/archive/master/lxc-master.tar.gz": "https://salsa.debian.org/lxc-team/lxc/-/archive/master/lxc-master.tar.gz",
@@ -150,6 +156,10 @@ def test_purl2url_get_inferred_urls():
         "pkg:cocoapods/AFNetworking@4.0.1": ["https://cocoapods.org/pods/AFNetworking"],
         "pkg:composer/psr/log@1.1.3": ["https://packagist.org/packages/psr/log#1.1.3"],
         "pkg:rubygems/package-name": ["https://rubygems.org/gems/package-name"],
+        "pkg:maven/org.apache.commons/commons-io@1.3.2": [
+            "https://repo.maven.apache.org/maven2/org/apache/commons/commons-io/1.3.2",
+            "https://repo.maven.apache.org/maven2/org/apache/commons/commons-io/1.3.2/commons-io-1.3.2.jar",
+        ],
         "pkg:bitbucket/birkenfeld": [],
     }
 

tests/test_packageurl.py

@@ -386,3 +386,17 @@ def test_vers_validation_ok():
 def test_vers_validation_fails():
     with pytest.raises(ValueError, match="must start with the 'vers:' URI scheme."):
         PackageURL.from_string("pkg:pypi/requests?vers=>=2.0")
+
+
+def test_no_encoding_to_string():
+    p = PackageURL(
+        type="nuget",
+        namespace="an:odd:space",
+        name="libiconv: character set conversion library",
+        version="1.9",
+        qualifiers={"package-id": "e11a609df352e292"},
+    )
+    assert (
+        p.to_string(encode=False)
+        == "pkg:nuget/an:odd:space/libiconv: character set conversion library@1.9?package-id=e11a609df352e292"
+    )