.pre-commit-config.yaml

@@ -26,7 +26,7 @@ repos:
     args: [-w, -L, "THIRDPARTY"]
 
 - repo: https://github.com/astral-sh/ruff-pre-commit
-  rev: v0.9.10  # Ruff version
+  rev: v0.11.0  # Ruff version
   hooks:
   - id: ruff
     args: [--fix, --show-fixes]

CHANGELOG.rst

@@ -6,6 +6,12 @@ Changelog
    Development Version
    ====================
 
+
+Version 0.24.1
+==============
+* Fixed multi plugin id was read from the wrong place by @henryiii, #240.
+* Implemented alternative plugin sorting, #243
+
 Version 0.24
 ============
 * Fix integration with ``SchemaStore`` by loading extra/side schemas, #226, #229.
@@ -21,7 +27,6 @@ Version 0.24
 
 Contributions by @henryiii.
 
-
 Version 0.23
 ============
 * Validate SPDX license expressions by @cdce8p in #217

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/

docs/index.rst

@@ -4,7 +4,7 @@ validate-pyproject
 
 **validate-pyproject** is a command line tool and Python library for validating
 ``pyproject.toml`` files based on JSON Schema, and includes checks for
-:pep:`517`, :pep:`518` and :pep:`621`.
+:pep:`517`, :pep:`518`, :pep:`621`, :pep:`639`, and :pep:`735`.
 
 
 Contents

src/validate_pyproject/api.py

@@ -98,7 +98,7 @@ def __init__(self, plugins: Sequence["PluginProtocol"] = ()):
         self._schemas: Dict[str, Tuple[str, str, Schema]] = {}
         # (which part of the TOML, who defines, schema)
 
-        top_level = typing.cast(dict, load(TOP_LEVEL_SCHEMA))  # Make it mutable
+        top_level = typing.cast("dict", load(TOP_LEVEL_SCHEMA))  # Make it mutable
         self._spec_version: str = top_level["$schema"]
         top_properties = top_level["properties"]
         tool_properties = top_properties["tool"].setdefault("properties", {})
@@ -116,12 +116,10 @@ def __init__(self, plugins: Sequence["PluginProtocol"] = ()):
             if plugin.tool:
                 allow_overwrite: Optional[str] = None
                 if plugin.tool in tool_properties:
-                    _logger.warning(
-                        f"{plugin.id} overwrites `tool.{plugin.tool}` schema"
-                    )
+                    _logger.warning(f"{plugin} overwrites `tool.{plugin.tool}` schema")
                     allow_overwrite = plugin.schema.get("$id")
                 else:
-                    _logger.info(f"{plugin.id} defines `tool.{plugin.tool}` schema")
+                    _logger.info(f"{plugin} defines `tool.{plugin.tool}` schema")
                 compatible = self._ensure_compatibility(
                     plugin.tool, plugin.schema, allow_overwrite
                 )
@@ -130,7 +128,7 @@ def __init__(self, plugins: Sequence["PluginProtocol"] = ()):
                 tool_properties[plugin.tool] = {"$ref": sref}
                 self._schemas[sid] = (f"tool.{plugin.tool}", plugin.id, plugin.schema)
             else:
-                _logger.info(f"Extra schema: {plugin.id}")
+                _logger.info(f"{plugin} defines extra schema {plugin.id}")
                 self._schemas[plugin.id] = (plugin.id, plugin.id, plugin.schema)
 
         self._main_id: str = top_level["$id"]
@@ -280,7 +278,7 @@ def __call__(self, pyproject: T) -> T:
                 self.schema, self.handlers, dict(self.formats), use_default=False
             )
             fn = partial(compiled, custom_formats=self._format_validators)
-            self._cache = typing.cast(ValidationFn, fn)
+            self._cache = typing.cast("ValidationFn", fn)
 
         with detailed_errors():
             self._cache(pyproject)

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
@@ -64,6 +67,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__
@@ -74,15 +81,20 @@ def help_text(self) -> str:
     def __repr__(self) -> str:
         return f"{self.__class__.__name__}({self.tool!r}, {self.id})"
 
+    def __str__(self) -> str:
+        return self.id
+
 
 class StoredPlugin:
-    def __init__(self, tool: str, schema: Schema):
+    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:
-        return self.schema.get("id", "MISSING ID")
+        return self._schema["$id"]  # type: ignore[no-any-return]
 
     @property
     def tool(self) -> str:
@@ -96,10 +108,17 @@ 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", "")
 
+    def __str__(self) -> str:
+        return self._source
+
     def __repr__(self) -> str:
         args = [repr(self.tool), self.id]
         if self.fragment:
@@ -108,7 +127,7 @@ def __repr__(self) -> str:
 
 
 if typing.TYPE_CHECKING:
-    _: PluginProtocol = typing.cast(PluginWrapper, None)
+    _: PluginProtocol = typing.cast("PluginWrapper", None)
 
 
 def iterate_entry_points(group: str) -> Iterable[EntryPoint]:
@@ -124,7 +143,7 @@ def iterate_entry_points(group: str) -> Iterable[EntryPoint]:
         # The select method was introduced in importlib_metadata 3.9 (and Python 3.10)
         # and the previous dict interface was declared deprecated
         select = typing.cast(
-            Callable[..., Iterable[EntryPoint]],
+            "Callable[..., Iterable[EntryPoint]]",
             getattr(entries, "select"),  # noqa: B009
         )  # typecheck gymnastics
         return select(group=group)
@@ -150,25 +169,40 @@ def load_from_multi_entry_point(
     try:
         fn = entry_point.load()
         output = fn()
+        id_ = f"{fn.__module__}.{fn.__name__}"
     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)
-    for schema in output.get("schemas", []):
-        yield StoredPlugin("", schema)
+        yield StoredPlugin(tool, schema, f"{id_}:{tool}", priority)
+    for i, schema in enumerate(output.get("schemas", [])):
+        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.plugin.tool or self.plugin.id, self.name, self.priority) < (
-            other.plugin.tool or other.plugin.id,
+        # **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.priority,
+            other.key(),
         )
 
 
@@ -184,23 +218,19 @@ def list_from_entry_points(
             plugin should be included.
     """
     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)
-        for e in sorted(
-            iterate_entry_points("validate_pyproject.multi_schema"),
-            key=lambda e: e.name,
-            reverse=True,
-        )
+        _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)
     )
     eps = chain(tool_eps, multi_eps)
-    dedup = {e.plugin.tool or e.plugin.id: e.plugin for e in sorted(eps, reverse=True)}
-    return list(dedup.values())[::-1]
+    dedup = {e.key(): e.plugin for e in sorted(eps)}
+    return list(dedup.values())
 
 
 class ErrorLoadingPlugin(RuntimeError):

src/validate_pyproject/remote.py

@@ -89,4 +89,4 @@ def load_store(pyproject_url: str) -> Generator[RemotePlugin, None, None]:
 if typing.TYPE_CHECKING:
     from .plugins import PluginProtocol
 
-    _: PluginProtocol = typing.cast(RemotePlugin, None)
+    _: PluginProtocol = typing.cast("RemotePlugin", None)