Change default plugin priority but allow customisation

Author: abravalheri

docs/dev-guide.rst

@@ -118,14 +118,11 @@ When using a :pep:`621`-compliant backend, the following can be add to your
 The plugin function will be automatically called with the ``tool_name``
 argument as same name as given to the entrypoint (e.g. :samp:`your_plugin({"your-tool"})`).
 
-Also notice plugins are activated in a specific order, using Python's built-in
-``sorted`` function.
-
 
 Providing multiple schemas
 --------------------------
 
-A second system is provided for providing multiple schemas in a single plugin.
+A second system is defined for providing multiple schemas in a single plugin.
 This is useful when a single plugin is responsible for multiple subtables
 under the ``tool`` table, or if you need to provide multiple schemas for a
 a single subtable.
@@ -158,6 +155,27 @@ An example of the plugin structure needed for this system is shown below:
 Fragments for schemas are also supported with this system; use ``#`` to split
 the tool name and fragment path in the dictionary key.
 
+
+.. admonition:: Experimental: Conflict Resolution
+
+   Please notice that when two plugins define the same ``tool``
+   (or auxiliary schemas with the same ``$id``),
+   an internal conflict resolution heuristic is employed to decide
+   which schema will take effect.
+
+   To influence this heuristic you can:
+
+   - Define a numeric ``.priority`` property in the functions
+     pointed by the ``validate_pyproject.tool_schema`` entry-points.
+   - Add a ``"priority"`` key with a numeric value into the dictionary
+     returned by the ``validate_pyproject.multi_schema`` plugins.
+
+   Typical values for ``priority`` are ``0`` and ``1``.
+
+   The exact order in which the plugins are loaded is considered an
+   implementation detail.
+
+
 .. _entry-point: https://setuptools.pypa.io/en/stable/userguide/entry_point.html#entry-points
 .. _JSON Schema: https://json-schema.org/
 .. _Python package: https://packaging.python.org/

src/validate_pyproject/plugins/__init__.py

@@ -25,6 +25,9 @@
 from .. import __version__
 from ..types import Plugin, Schema
 
+_DEFAULT_MULTI_PRIORITY = 0
+_DEFAULT_TOOL_PRIORITY = 1
+
 
 class PluginProtocol(Protocol):
     @property
@@ -42,6 +45,9 @@ def help_text(self) -> str: ...
     @property
     def fragment(self) -> str: ...
 
+    @property
+    def priority(self) -> float: ...
+
 
 class PluginWrapper:
     def __init__(self, tool: str, load_fn: Plugin):
@@ -64,6 +70,10 @@ def schema(self) -> Schema:
     def fragment(self) -> str:
         return ""
 
+    @property
+    def priority(self) -> float:
+        return getattr(self._load_fn, "priority", _DEFAULT_TOOL_PRIORITY)
+
     @property
     def help_text(self) -> str:
         tpl = self._load_fn.__doc__
@@ -79,10 +89,11 @@ def __str__(self) -> str:
 
 
 class StoredPlugin:
-    def __init__(self, tool: str, schema: Schema, source: str):
+    def __init__(self, tool: str, schema: Schema, source: str, priority: float):
         self._tool, _, self._fragment = tool.partition("#")
         self._schema = schema
         self._source = source
+        self._priority = priority
 
     @property
     def id(self) -> str:
@@ -100,6 +111,10 @@ def schema(self) -> Schema:
     def fragment(self) -> str:
         return self._fragment
 
+    @property
+    def priority(self) -> float:
+        return self._priority
+
     @property
     def help_text(self) -> str:
         return self.schema.get("description", "")
@@ -161,23 +176,34 @@ def load_from_multi_entry_point(
     except Exception as ex:
         raise ErrorLoadingPlugin(entry_point=entry_point) from ex
 
+    priority = output.get("priority", _DEFAULT_MULTI_PRIORITY)
     for tool, schema in output["tools"].items():
-        yield StoredPlugin(tool, schema, f"{id_}:{tool}")
+        yield StoredPlugin(tool, schema, f"{id_}:{tool}", priority)
     for i, schema in enumerate(output.get("schemas", [])):
-        yield StoredPlugin("", schema, f"{id_}:{i}")
+        yield StoredPlugin("", schema, f"{id_}:{i}", priority)
 
 
 class _SortablePlugin(NamedTuple):
-    priority: int
     name: str
     plugin: Union[PluginWrapper, StoredPlugin]
 
     def key(self) -> str:
         return self.plugin.tool or self.plugin.id
 
     def __lt__(self, other: Any) -> bool:
-        return (self.priority, self.name, self.key()) < (
-            other.priority,
+        # **Major concern**:
+        # Consistency and reproducibility on which entry-points have priority
+        # for a given environment.
+        # The plugin with higher priority overwrites the schema definition.
+        # The exact order that they are listed itself is not important for now.
+        # **Implementation detail**:
+        # By default, "single tool plugins" have priority 1 and "multi plugins"
+        # have priority 0.
+        # The order that the plugins will be listed is inverse to the priority.
+        # If 2 plugins have the same numerical priority, the one whose
+        # entry-point name is "higher alphabetically" wins.
+        return (self.plugin.priority, self.name, self.key()) < (
+            other.plugin.priority,
             other.name,
             other.key(),
         )
@@ -194,22 +220,13 @@ def list_from_entry_points(
             loaded and included (or not) in the final list. A ``True`` return means the
             plugin should be included.
     """
-    # **Major concern**:
-    # Consistency and reproducibility on which entry-points have priority
-    # for a given environment.
-    # The plugin with higher priority overwrites the schema definition.
-    # The exact order itself is not important for now.
-    # **Implementation detail**:
-    # Tool plugins are loaded first, so they are listed first than other schemas,
-    # but multi plugins always have priority, overwriting the tool schemas.
-    # The "higher alphabetically" an entry-point name, the more priority.
     tool_eps = (
-        _SortablePlugin(0, e.name, load_from_entry_point(e))
+        _SortablePlugin(e.name, load_from_entry_point(e))
         for e in iterate_entry_points("validate_pyproject.tool_schema")
         if filtering(e)
     )
     multi_eps = (
-        _SortablePlugin(1, e.name, p)
+        _SortablePlugin(e.name, p)
         for e in iterate_entry_points("validate_pyproject.multi_schema")
         for p in load_from_multi_entry_point(e)
         if filtering(e)

tests/test_plugins.py

@@ -83,14 +83,14 @@ def test_empty_help_text(self):
         def _fn1(_):
             return {}
 
-        pw = plugins.StoredPlugin("name", {}, "id1")
+        pw = plugins.StoredPlugin("name", {}, "id1", 0)
         assert pw.help_text == ""
 
         def _fn2(_):
             """Help for `${tool}`"""
             return {}
 
-        pw = plugins.StoredPlugin("name", {"description": "Help for me"}, "id2")
+        pw = plugins.StoredPlugin("name", {"description": "Help for me"}, "id2", 0)
         assert pw.help_text == "Help for me"
 
 
@@ -158,30 +158,31 @@ def test_combined_plugins(monkeypatch, epname):
             "tools": {
                 "example1": {"$id": "example1"},
                 "example2": {"$id": "example2"},
-                "example4": {"$id": "example4"},
+                "example3": {"$id": "example3"},
             }
         }
     )
     tool_eps(name="example1", value="test_module:f1")(lambda _: {"$id": "ztool1"})
     tool_eps(name="example2", value="test_module:f2")(lambda _: {"$id": "atool2"})
-    tool_eps(name="example3", value="test_module:f2")(lambda _: {"$id": "tool3"})
+    tool_eps(name="example4", value="test_module:f2")(lambda _: {"$id": "tool4"})
 
     monkeypatch.setattr(plugins, "iterate_entry_points", fake_eps.get)
 
     lst = plugins.list_from_entry_points()
+    print(lst)
     assert len(lst) == 4
 
     assert lst[0].tool == "example1"
-    assert isinstance(lst[0], StoredPlugin)
+    assert isinstance(lst[0], PluginWrapper)
 
     assert lst[1].tool == "example2"
-    assert isinstance(lst[1], StoredPlugin)
+    assert isinstance(lst[1], PluginWrapper)
 
     assert lst[2].tool == "example3"
-    assert isinstance(lst[2], PluginWrapper)
+    assert isinstance(lst[2], StoredPlugin)
 
     assert lst[3].tool == "example4"
-    assert isinstance(lst[3], StoredPlugin)
+    assert isinstance(lst[3], PluginWrapper)
 
 
 def test_several_multi_plugins(monkeypatch):
@@ -200,10 +201,42 @@ def test_several_multi_plugins(monkeypatch):
         monkeypatch.setattr(plugins, "iterate_entry_points", eps.get)
         # entry-point names closer to "zzzzzzzz..." have priority
         (plugin1, plugin2) = plugins.list_from_entry_points()
+        print(plugin1, plugin2)
         assert plugin1.schema["$id"] == "example1"
         assert plugin2.schema["$id"] == "example3"
 
 
+def test_custom_priority(monkeypatch):
+    fake_eps = _FakeEntryPoints(monkeypatch)
+    tool_eps = fake_eps.group("validate_pyproject.tool_schema")
+    multi_eps = fake_eps.group("validate_pyproject.multi_schema")
+
+    multi_schema = {"tools": {"example": {"$id": "multi-eps"}}}
+    multi_eps(name="example", value="test_module:f")(lambda: multi_schema)
+
+    @tool_eps(name="example", value="test_module1:f1")
+    def tool_schema1(_name):
+        return {"$id": "tool-eps-1"}
+
+    @tool_eps(name="example", value="test_module2:f1")
+    def tool_schema2(_name):
+        return {"$id": "tool-eps-2"}
+
+    monkeypatch.setattr(plugins, "iterate_entry_points", fake_eps.get)
+    (winner,) = plugins.list_from_entry_points()  # default: tool with "higher" ep name
+    assert winner.schema["$id"] == "tool-eps-2"
+
+    tool_schema1.priority = 1.1
+    (winner,) = plugins.list_from_entry_points()  # default: tool has priority
+    assert winner.schema["$id"] == "tool-eps-1"
+
+    tool_schema1.priority = 0.1
+    tool_schema2.priority = 0.2
+    multi_schema["priority"] = 0.9
+    (winner,) = plugins.list_from_entry_points()  # custom higher priority wins
+    assert winner.schema["$id"] == "multi-eps"
+
+
 def test_broken_multi_plugin(monkeypatch):
     fake_eps = _FakeEntryPoints(monkeypatch, "validate_pyproject.multi_schema")
     fake_eps(name="broken", value="test_module.f")(lambda: {}["no-such-key"])