Add an API to describe variant using labels

Add a minimal API that lets plugins process the variant description
and add short labels that could be used to describe the wheel.
The labels are entirely optional -- plugins may not return any,
and clients may ignore them.  The design also assumes that the client
is responsible for choosing how many labels to use before truncating --
though I suppose I'll add a helper function to `variantlib` for that
purpose.

The design assumes that plugin get complete unfiltered
`VariantDescription` -- and therefore also see variant metadata from
other plugins.  I don't think that's really a problem, though it assumes
that the plugin must compare both against provider and key names.

At this point, the protocol makes the API mandatory, even if it would
only return an empty list unconditionally.  Perhaps we should
make the function optional somehow instead.

Author: mgorny

tests/test_plugins.py

@@ -5,6 +5,7 @@
 
 from variantlib.base import PluginBase
 from variantlib.config import KeyConfig, ProviderConfig
+from variantlib.meta import VariantDescription, VariantMeta
 from variantlib.plugins import PluginLoader
 
 
@@ -20,6 +21,12 @@ def get_supported_configs(self) -> Optional[ProviderConfig]:
             ],
         )
 
+    def get_variant_labels(self, variant_desc: VariantDescription) -> list[str]:
+        for meta in variant_desc:
+            if meta.provider == self.__name__ and meta.key == "key1":
+                return [meta.value.removeprefix("val")]
+        return []
+
 
 # NB: this plugin deliberately does not inherit from PluginBase
 # to test that we don't rely on that inheritance
@@ -34,6 +41,11 @@ def get_supported_configs(self) -> Optional[ProviderConfig]:
             ],
         )
 
+    def get_variant_labels(self, variant_desc: VariantDescription) -> list[str]:
+        if VariantMeta(self.__name__, "key3", "val3a") in variant_desc:
+            return ["sec"]
+        return []
+
 
 class MockedPluginC(PluginBase):
     namespace = "incompatible_plugin"
@@ -48,6 +60,13 @@ class ClashingPlugin(PluginBase):
     def get_supported_configs(self) -> Optional[ProviderConfig]:
         return None
 
+    def get_variant_labels(self, variant_desc: VariantDescription) -> list[str]:
+        ret = []
+        for meta in variant_desc:
+            if meta.provider == self.__name__ and meta.value == "on":
+                ret.append(meta.key)
+        return ret
+
 
 @dataclass
 class MockedDistribution:
@@ -137,3 +156,36 @@ def test_namespace_clash(mocker):
     assert "same namespace test_plugin" in str(exc)
     assert "test-plugin" in str(exc)
     assert "clashing-plugin" in str(exc)
+
+
+@pytest.mark.parametrize("variant_desc,expected",
+[
+    (VariantDescription([
+        VariantMeta("test_plugin", "key1", "val1a"),
+        VariantMeta("test_plugin", "key2", "val2b"),
+        VariantMeta("second_plugin", "key3", "val3a"),
+        VariantMeta("other_plugin", "flag2", "on"),
+    ]), ["1a", "sec", "flag2"]),
+    (VariantDescription([
+        # note that VariantMetas don't actually have to be supported
+        # by the system in question -- we could be cross-building
+        # for another system
+        VariantMeta("test_plugin", "key1", "val1f"),
+        VariantMeta("test_plugin", "key2", "val2b"),
+        VariantMeta("second_plugin", "key3", "val3a"),
+    ]), ["1f", "sec"]),
+    (VariantDescription([
+        VariantMeta("test_plugin", "key2", "val2b"),
+        VariantMeta("second_plugin", "key3", "val3a"),
+    ]), ["sec"]),
+    (VariantDescription([
+        VariantMeta("test_plugin", "key2", "val2b"),
+    ]), []),
+    (VariantDescription([
+        VariantMeta("test_plugin", "key2", "val2b"),
+        VariantMeta("other_plugin", "flag1", "on"),
+        VariantMeta("other_plugin", "flag2", "on"),
+    ]), ["flag1", "flag2"]),
+])
+def test_get_variant_labels(mocked_plugin_loader, variant_desc, expected):
+    assert mocked_plugin_loader.get_variant_labels(variant_desc) == expected

variantlib/base.py

@@ -2,6 +2,7 @@
 from typing import Protocol, runtime_checkable
 
 from variantlib.config import ProviderConfig
+from variantlib.meta import VariantDescription
 
 
 @runtime_checkable
@@ -17,6 +18,10 @@ def get_supported_configs(self) -> ProviderConfig:
         """Get supported configs for the current system"""
         ...
 
+    def get_variant_labels(self, variant_desc: VariantDescription) -> list[str]:
+        """Get list of short labels to describe the variant"""
+        ...
+
 
 class PluginBase(ABC):
     """An abstract base class that can be used to implement plugins"""
@@ -26,3 +31,6 @@ def namespace(self) -> str: ...
 
     @abstractmethod
     def get_supported_configs(self) -> ProviderConfig: ...
+
+    def get_variant_labels(self, variant_desc: VariantDescription) -> list[str]:
+        return []

variantlib/plugins.py

@@ -92,3 +92,12 @@ def get_dist_name_mapping(self) -> dict[str, str]:
         """Get a mapping from plugin names to distribution names"""
 
         return self._dist_names
+
+    def get_variant_labels(self, variant_desc: VariantDescription) -> list[str]:
+        """Get list of short labels to describe the variant"""
+
+        labels = []
+        for plugin in self._plugins.values():
+            labels += plugin.get_variant_labels(variant_desc)
+
+        return labels