lockss-turtles 0.5.0.dev4__py3-none-any.whl → 0.6.0__py3-none-any.whl

lockss/turtles/plugin_set.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-# Copyright (c) 2000-2023, Board of Trustees of Leland Stanford Jr. University
+# Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
 #
 # Redistribution and use in source and binary forms, with or without
 # modification, are permitted provided that the following conditions are met:
@@ -28,97 +28,376 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 
-import importlib.resources
+"""
+Module to represent plugin sets and plugin set catalogs.
+"""
+
+# Remove in Python 3.14; see https://stackoverflow.com/a/33533514
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
 import os
 from pathlib import Path
 import shlex
 import subprocess
 import sys
+from typing import Annotated, Any, Callable, ClassVar, Literal, Optional, Union
+
+from pydantic import BaseModel, Field
+
+from .plugin import Plugin, PluginIdentifier
+from .util import BaseModelWithRoot
+
+
+#: A type alias for the plugin set catalog kind.
+PluginSetCatalogKind = Literal['PluginSetCatalog']
+
+
+class PluginSetCatalog(BaseModelWithRoot):
+    """
+    A Pydantic model (``lockss.turtles.util.BaseModelWithRoot``) to represent a
+    plugin set catalog.
+    """
+
+    #: This object's kind.
+    kind: PluginSetCatalogKind = Field(title='Kind',
+                                       description="This object's kind")
+
+    #: A non-empty list of plugin set files.
+    plugin_set_files: list[str] = Field(alias='plugin-set-files',
+                                        min_length=1,
+                                        title='Plugin Set Files',
+                                        description="A non-empty list of plugin set files")
+
+    def get_plugin_set_files(self) -> list[Path]:
+        """
+        Return this plugin set catalog's list of plugin set definition file
+        paths (relative to the root if not absolute).
+
+        :return: A list of plugin set definition file paths.
+        :rtype: list[Path]
+        """
+        return [self.get_root().joinpath(p) for p in self.plugin_set_files]
+
+
+#: A type alias for the plugin set builder type.
+PluginSetBuilderType = Literal['ant', 'maven']
+
+
+class BasePluginSetBuilder(BaseModelWithRoot, ABC):
+    """
+    An abstract Pydantic model (``lockss.turtles.util.BaseModelWithRoot``) to
+    represent a plugin set builder, with concrete implementations
+    ``MavenPluginSetBuilder`` and ``AntPluginSetBuilder``.
+    """
+
+    #: Pydantic definition of the ``type`` field.
+    TYPE_FIELD: ClassVar[dict[str, str]] = dict(title='Plugin Builder Type',
+                                                description='A plugin builder type')
+
+    #: Pydantic definition of the ``main`` field.
+    MAIN_FIELD: ClassVar[dict[str, str]] = dict(title='Main Code Path',
+                                                description="The path to the plugins' source code, relative to the root of the project")
+
+    #: Pydantic definition of the ``test`` field.
+    TEST_FIELD: ClassVar[dict[str, str]] = dict(title='Test Code Path',
+                                                description="The path to the plugins' unit tests, relative to the root of the project")
+
+    @abstractmethod
+    def build_plugin(self,
+                     plugin_id: PluginIdentifier,
+                     keystore_path: Path,
+                     keystore_alias: str,
+                     keystore_password=None) -> tuple[Path, Plugin]:
+        """
+        Builds the given plugin, using the given plugin signing credentials.
+
+        :param plugin_id: A plugin identifier.
+        :type plugin_id: PluginIdentifier
+        :param keystore_path: The path to the plugin signing keystore.
+        :type keystore_path: Path
+        :param keystore_alias: The signing alias to use from the plugin signing
+                               keystore.
+        :type keystore_alias: str
+        :param keystore_password: The signing password.
+        :type keystore_password: Any
+        :return: A tuple of the plugin JAR path and the corresponding ``Plugin``
+                 object.
+        :rtype: tuple[Path, Plugin]
+        """
+        pass # FIXME: typing of keystore_password
+
+    def get_main(self) -> Path:
+        """
+        Returns this plugin set builder's main code path (relative to the root
+        if not absolute).
+
+        :return: This plugin set's main code path.
+        :rtype: Path
+        :raises ValueError: If this object is not properly initialized.
+        """
+        return self.get_root().joinpath(self._get_main())
+
+    def get_test(self) -> Path:
+        """
+        Returns this plugin set builder's unit test path (relative to the root
+        if not absolute).
+
+        :return: This plugin set's unit test path.
+        :rtype: Path
+        :raises ValueError: If this object is not properly initialized.
+        """
+        return self.get_root().joinpath(self._get_test())
+
+    def get_type(self) -> PluginSetBuilderType:
+        """
+        Returns this plugin set builder's type.
+
+        :return: This plugin set builder's type.
+        :rtype: PluginSetBuilderType
+        """
+        return getattr(self, 'type')
+
+    def has_plugin(self,
+                   plugin_id: PluginIdentifier) -> bool:
+        """
+        Determines if the given plugin identifier represents a plugin that is
+        present in the plugin set.
+
+        :param plugin_id: A plugin identifier.
+        :type plugin_id: PluginIdentifier
+        :return: Whether the plugin is present in the plugin set.
+        :rtype: bool
+        """
+        return self._plugin_path(plugin_id).is_file()
 
-from lockss.turtles.plugin import Plugin
-import lockss.turtles.resources
-from lockss.turtles.util import _load_and_validate, _path
-
-
-class PluginSetCatalog(object):
-
-    PLUGIN_SET_CATALOG_SCHEMA = 'plugin-set-catalog-schema.json'
-
-    @staticmethod
-    def from_path(plugin_set_catalog_path):
-        plugin_set_catalog_path = _path(plugin_set_catalog_path)
-        with importlib.resources.path(lockss.turtles.resources, PluginSetCatalog.PLUGIN_SET_CATALOG_SCHEMA) as plugin_set_catalog_schema_path:
-            parsed = _load_and_validate(plugin_set_catalog_schema_path, plugin_set_catalog_path)
-            return PluginSetCatalog(parsed)
-
-    def __init__(self, parsed):
-        super().__init__()
-        self._parsed = parsed
-
-    def get_plugin_set_files(self):
-        return self._parsed['plugin-set-files']
-
-
-class PluginSet(object):
-
-    PLUGIN_SET_SCHEMA = 'plugin-set-schema.json'
-
-    @staticmethod
-    def from_path(plugin_set_file_path):
-        plugin_set_file_path = _path(plugin_set_file_path)
-        with importlib.resources.path(lockss.turtles.resources, PluginSet.PLUGIN_SET_SCHEMA) as plugin_set_schema_path:
-            lst = _load_and_validate(plugin_set_schema_path, plugin_set_file_path, multiple=True)
-            return [PluginSet._from_obj(parsed, plugin_set_file_path) for parsed in lst]
-
-    @staticmethod
-    def _from_obj(parsed, plugin_set_file_path):
-        typ = parsed['builder']['type']
-        if typ == AntPluginSet.TYPE:
-            return AntPluginSet(parsed, plugin_set_file_path)
-        elif typ == MavenPluginSet.TYPE:
-            return MavenPluginSet(parsed, plugin_set_file_path)
-        else:
-            raise Exception(f'{plugin_set_file_path!s}: unknown builder type: {typ}')
-
-    def __init__(self, parsed):
-        super().__init__()
-        self._parsed = parsed
-
-    # Returns (jar_path, plugin)
-    def build_plugin(self, plugin_id, keystore_path, keystore_alias, keystore_password=None):
-        raise NotImplementedError('build_plugin')
-
-    def get_builder_type(self):
-        return self._parsed['builder']['type']
-
-    def get_id(self):
-        return self._parsed['id']
+    def make_plugin(self,
+                    plugin_id: PluginIdentifier) -> Plugin:
+        """
+        Makes a ``Plugin`` object from the given plugin identifier.
 
-    def get_name(self):
-        return self._parsed['name']
+        :param plugin_id: A plugin identifier.
+        :type plugin_id: PluginIdentifier
+        :return: The corresponding ``Plugin`` object.
+        :rtype: Plugin
+        """
+        return Plugin.from_path(self._plugin_path(plugin_id))
 
-    def has_plugin(self, plugin_id):
-        raise NotImplementedError('has_plugin')
+    def _get_main(self) -> str:
+        """
+        Returns the concrete implementation's ``main`` field.
+
+        :return: The ``main`` field.
+        :rtype: str
+        """
+        return getattr(self, 'main')
+
+    def _get_test(self) -> str:
+        """
+        Returns the concrete implementation's ``test`` field.
+
+        :return: The ``test`` field.
+        :rtype: str
+        """
+        return getattr(self, 'test')
+
+    def _plugin_path(self,
+                     plugin_id: PluginIdentifier) -> Path:
+        """
+        Returns the path of the plugin file for the given plugin identifier
+        relative to the plugin set's main code path.
+
+        :param plugin_id: A plugin identifier.
+        :type plugin_id: PluginIdentifier
+        :return: The plugin file.
+        :rtype: Path
+        """
+        return self.get_main().joinpath(Plugin.id_to_file(plugin_id))
+
+
+class MavenPluginSetBuilder(BasePluginSetBuilder):
+    """
+    A plugin set builder that uses `Java <https://www.oracle.com/java/>`_
+    Development Kit (JDK) 17 and `Apache Maven <https://maven.apache.org/>`_,
+    with the parent POM
+    `org.lockss:lockss-plugins-parent-pom <https://central.sonatype.com/artifact/org.lockss/lockss-plugins-parent-pom>`_.
+    """
+
+    #: The default value for ``main``.
+    DEFAULT_MAIN: ClassVar[str] = 'src/main/java'
+
+    #: The default value for ``test``.
+    DEFAULT_TEST: ClassVar[str] = 'src/test/java'
+
+    #: This Plugin set builder's type.
+    type: Literal['maven'] = Field(**BasePluginSetBuilder.TYPE_FIELD)
+
+    #: This plugin set builder's main code path.
+    main: str = Field(DEFAULT_MAIN,
+                      **BasePluginSetBuilder.MAIN_FIELD)
+
+    #: This plugin set builder's unit test path.
+    test: str = Field(DEFAULT_TEST,
+                      **BasePluginSetBuilder.TEST_FIELD)
+
+    #: An internal flag to remember if a build has occurred.
+    _built: bool
+
+    def build_plugin(self,
+                     plugin_id: PluginIdentifier,
+                     keystore_path: Path,
+                     keystore_alias: str,
+                     keystore_password: Optional[Callable[[], str]]=None) -> tuple[Path, Plugin]:
+        """
+        Builds the given plugin with the supplied plugin signing credentials.
+
+        :param plugin_id: A plugin identifier.
+        :type plugin_id: PluginIdentifier
+        :param keystore_path: The path to the plugin signing keystore.
+        :type keystore_path: Path
+        :param keystore_alias: The alias to use in the plugin signing keystore.
+        :type keystore_alias: str
+        :param keystore_password: The plugin signing password.
+        :type keystore_password:
+        :return: A tuple of the built and signed JAR file and a Plugin object
+                 instantiated from it.
+        :rtype: tuple[Path, Plugin]
+        :raises subprocess.CalledProcessError: If a subprocess fails.
+        :raises FileNotFoundError: If the expected built and signed plugin JAR
+                                   path is unexpectedly not found despite the
+                                   build.
+        """
+        self._big_build(keystore_path, keystore_alias, keystore_password=keystore_password)
+        return self._little_build(plugin_id)
 
-    def make_plugin(self, plugin_id):
-        raise NotImplementedError('make_plugin')
+    def model_post_init(self,
+                        context: Any) -> None:
+        """
+        Pydantic post-initialization method to initialize the ``_built`` flag.
 
+        :param context: The Pydantic context.
+        :type context: Any
+        """
+        super().model_post_init(context)
+        self._built = False
 
-class AntPluginSet(PluginSet):
+    def _big_build(self,
+                   keystore_path: Path,
+                   keystore_alias: str,
+                   keystore_password: Optional[Callable[[], str]]=None) -> None:
+        """
+        Runs ``mvn package`` on the project if the ``_built`` flag is False.
+
+        :param keystore_path: The path to the plugin signing keystore.
+        :type keystore_path: Path
+        :param keystore_alias: The alias to use in the plugin signing keystore.
+        :type keystore_alias: str
+        :param keystore_password: The plugin signing password.
+        :type keystore_password: Optional[Callable[[], str]]
+        :raises subprocess.CalledProcessError: If a subprocess fails.
+        """
+        if not self._built:
+            # Do build
+            cmd = ['mvn', 'package',
+                   f'-Dkeystore.file={keystore_path!s}',
+                   f'-Dkeystore.alias={keystore_alias}']
+            if keystore_password:
+                cmd.append(f'-Dkeystore.password={keystore_password()}')
+            try:
+                subprocess.run(cmd, cwd=self.get_root(), check=True, stdout=sys.stdout, stderr=sys.stderr)
+            except subprocess.CalledProcessError as cpe:
+                raise self._sanitize(cpe)
+            self._built = True
 
-    TYPE = 'ant'
+    def _little_build(self,
+                      plugin_id: PluginIdentifier) -> tuple[Path, Plugin]:
+        """
+        In the Maven implementation, essentially a no-op (keeping for parallel
+        structure with the legacy Ant plugin set builder).
+
+        :param plugin_id: A plugin identifier.
+        :type plugin_id: PluginIdentifier
+        :return: A tuple of the built and signed JAR file and a Plugin object
+                 instantiated from it.
+        :rtype: tuple[Path, Plugin]
+        :raises FileNotFoundError: If the expected built and signed plugin JAR
+                                   path is unexpectedly not found despite the
+                                   build.
+        """
+        jar_path = self.get_root().joinpath('target', 'pluginjars', f'{plugin_id}.jar')
+        if not jar_path.is_file():
+            raise FileNotFoundError(str(jar_path))
+        return jar_path, Plugin.from_jar(jar_path)
 
-    DEFAULT_MAIN = 'plugins/src'
+    def _sanitize(self,
+                  called_process_error: subprocess.CalledProcessError) -> subprocess.CalledProcessError:
+        """
+        Alters the ``-Dkeystore.password=`` portion of a called process error.
 
-    DEFAULT_TEST = 'plugins/test/src'
+        :param called_process_error: A called process error.
+        :return: The same called process error, with ``-Dkeystore.password=``
+                 altered in ``cmd``.
+        """
+        cmd = called_process_error.cmd[:]
+        for i in range(len(cmd)):
+            if cmd[i].startswith('-Dkeystore.password='):
+                cmd[i] = '-Dkeystore.password=<password>'
+        called_process_error.cmd = ' '.join([shlex.quote(c) for c in cmd])
+        return called_process_error
 
-    def __init__(self, parsed, path):
-        super().__init__(parsed)
-        self._built = False
-        self._root = path.parent
 
-    # Returns (jar_path, plugin)
-    def build_plugin(self, plugin_id, keystore_path, keystore_alias, keystore_password=None):
+class AntPluginSetBuilder(BasePluginSetBuilder):
+    """
+    A plugin set builder that uses `Java <https://www.oracle.com/java/>`_
+    Development Kit (JDK) 8 and `Apache Ant <https://ant.apache.org/>`_,
+    with the legacy LOCKSS 1.x build system.
+    """
+
+    #: Default value for the ``main`` field.
+    DEFAULT_MAIN: ClassVar[str] = 'plugins/src'
+
+    #: Default value for the ``test`` field.
+    DEFAULT_TEST: ClassVar[str] = 'plugins/test/src'
+
+    #: This plugin set builder's type.
+    type: Literal['ant'] = Field(**BasePluginSetBuilder.TYPE_FIELD)
+
+    #: This plugin set builder's main code path.
+    main: str = Field(DEFAULT_MAIN,
+                      **BasePluginSetBuilder.MAIN_FIELD)
+
+    #: This plugin set builder's unit test path.
+    test: str = Field(DEFAULT_TEST,
+                      **BasePluginSetBuilder.TEST_FIELD)
+
+    #: An internal flag to remember if a build has occurred.
+    _built: bool
+
+    def build_plugin(self,
+                     plugin_id: PluginIdentifier,
+                     keystore_path: Path,
+                     keystore_alias: str,
+                     keystore_password: Optional[Callable[[], str]]=None) -> tuple[Path, Plugin]:
+        """
+        Builds the given plugin with the supplied plugin signing credentials.
+
+        :param plugin_id: A plugin identifier.
+        :type plugin_id: PluginIdentifier
+        :param keystore_path: The path to the plugin signing keystore.
+        :type keystore_path: Path
+        :param keystore_alias: The alias to use in the plugin signing keystore.
+        :type keystore_alias: str
+        :param keystore_password: The plugin signing password.
+        :type keystore_password: Optional[Callable[[], str]]
+        :return: A tuple of the built and signed JAR file and a Plugin object
+                 instantiated from it.
+        :rtype: tuple[Path, Plugin]
+        :raises Exception: If ``JAVA_HOME`` is not set in the environment.
+        :raises subprocess.CalledProcessError: If a subprocess fails.
+        :raises FileNotFoundError: If the expected built and signed plugin JAR
+                                   path is unexpectedly not found despite the
+                                   build.
+        """
         # Prerequisites
         if 'JAVA_HOME' not in os.environ:
             raise Exception('error: JAVA_HOME must be set in your environment')
@@ -127,43 +406,57 @@ class AntPluginSet(PluginSet):
         # Little build
         return self._little_build(plugin_id, keystore_path, keystore_alias, keystore_password=keystore_password)
 
-    def get_main(self):
-        return self._parsed.get('main', AntPluginSet.DEFAULT_MAIN)
-
-    def get_main_path(self):
-        return self.get_root_path().joinpath(self.get_main())
-
-    def get_root(self):
-        return self._root
-
-    def get_root_path(self):
-        return Path(self.get_root()).expanduser().resolve()
-
-    def get_test(self):
-        return self._parsed.get('test', AntPluginSet.DEFAULT_TEST)
+    def model_post_init(self,
+                        context: Any) -> None:
+        """
+        Pydantic post-initialization method to initialize the ``_built`` flag.
 
-    def get_test_path(self):
-        return self.get_root_path().joinpath(self.get_test())
-
-    def has_plugin(self, plugin_id):
-        return self._plugin_path(plugin_id).is_file()
+        :param context: The Pydantic context.
+        :type context: Any
+        """
+        super().model_post_init(context)
+        self._built = False
 
-    def make_plugin(self, plugin_id):
-        return Plugin.from_path(self._plugin_path(plugin_id))
+    def _big_build(self) -> None:
+        """
+        Runs ``ant load-plugins`` if the ``_built`` flag is False.
 
-    def _big_build(self):
+        :raises subprocess.CalledProcessError: If a subprocess fails.
+        """
         if not self._built:
             # Do build
             subprocess.run('ant load-plugins',
-                           shell=True, cwd=self.get_root_path(), check=True, stdout=sys.stdout, stderr=sys.stderr)
+                           shell=True, cwd=self.get_root(), check=True, stdout=sys.stdout, stderr=sys.stderr)
             self._built = True
 
-    # Returns (jar_path, plugin)
-    def _little_build(self, plugin_id, keystore_path, keystore_alias, keystore_password=None):
+    def _little_build(self,
+                      plugin_id: PluginIdentifier,
+                      keystore_path: Path,
+                      keystore_alias: str,
+                      keystore_password: Optional[Callable[[], str]]=None) -> tuple[Path, Plugin]:
+        """
+        Performs the "little build" of the given plugin.
+
+        :param plugin_id: A plugin identifier.
+        :type plugin_id: PluginIdentifier
+        :param keystore_path: The path to the plugin signing keystore.
+        :type keystore_path: Path
+        :param keystore_alias: The alias to use in the plugin signing keystore.
+        :type keystore_alias: str
+        :param keystore_password: The plugin signing password.
+        :type keystore_password: Optional[Callable[[], str]]
+        :return: A tuple of the built and signed JAR file and a Plugin object
+                 instantiated from it.
+        :rtype: tuple[Path, Plugin]
+        :raises subprocess.CalledProcessError: If a subprocess fails.
+        :raises FileNotFoundError: If the expected built and signed plugin JAR
+                                   path is unexpectedly not found despite the
+                                   build.
+        """
         orig_plugin = None
         cur_id = plugin_id
         # Get all directories for jarplugin -d
-        dirs = list()
+        dirs = []
         while cur_id is not None:
             cur_plugin = self.make_plugin(cur_id)
             orig_plugin = orig_plugin or cur_plugin
@@ -177,112 +470,166 @@ class AntPluginSet(PluginSet):
             cur_id = cur_plugin.get_parent_identifier()
         # Invoke jarplugin
         jar_fstr = Plugin.id_to_file(plugin_id)
-        jar_path = self.get_root_path().joinpath('plugins/jars', f'{plugin_id}.jar')
+        jar_path = self.get_root().joinpath('plugins/jars', f'{plugin_id}.jar')
         jar_path.parent.mkdir(parents=True, exist_ok=True)
         cmd = ['test/scripts/jarplugin',
                '-j', str(jar_path),
                '-p', str(jar_fstr)]
         for d in dirs:
             cmd.extend(['-d', d])
-        subprocess.run(cmd, cwd=self.get_root_path(), check=True, stdout=sys.stdout, stderr=sys.stderr)
+        subprocess.run(cmd, cwd=self.get_root(), check=True, stdout=sys.stdout, stderr=sys.stderr)
         # Invoke signplugin
         cmd = ['test/scripts/signplugin',
                '--jar', str(jar_path),
                '--alias', keystore_alias,
                '--keystore', str(keystore_path)]
-        if keystore_password is not None:
-            cmd.extend(['--password', keystore_password])
+        if keystore_password:
+            cmd.extend(['--password', keystore_password()])
         try:
-            subprocess.run(cmd, cwd=self.get_root_path(), check=True, stdout=sys.stdout, stderr=sys.stderr)
+            subprocess.run(cmd, cwd=self.get_root(), check=True, stdout=sys.stdout, stderr=sys.stderr)
         except subprocess.CalledProcessError as cpe:
             raise self._sanitize(cpe)
         if not jar_path.is_file():
             raise FileNotFoundError(str(jar_path))
-        return (jar_path, orig_plugin)
+        return jar_path, orig_plugin
+
+    # def _plugin_path(self, plugin_id: PluginIdentifier) -> Path:
+    #     return self.get_main().joinpath(Plugin.id_to_file(plugin_id))
 
-    def _plugin_path(self, plugin_id):
-        return Path(self.get_main_path()).joinpath(Plugin.id_to_file(plugin_id))
+    def _sanitize(self,
+                  called_process_error: subprocess.CalledProcessError) -> subprocess.CalledProcessError:
+        """
+        Alters the value of ``--password`` in a called process error.
 
-    def _sanitize(self, called_process_error):
+        :param called_process_error: A called process error.
+        :return: The same called process error, with the value of ``--password``
+                 altered in ``cmd``.
+        """
         cmd = called_process_error.cmd[:]
-        i = 0
-        for i in range(len(cmd)):
-            if i > 1 and cmd[i - 1] == '--password':
+        for i in range(1, len(cmd)):
+            if cmd[i - 1] == '--password':
                 cmd[i] = '<password>'
         called_process_error.cmd = ' '.join([shlex.quote(c) for c in cmd])
         return called_process_error
 
 
-class MavenPluginSet(PluginSet):
-
-    TYPE = 'maven'
-
-    DEFAULT_MAIN = 'src/main/java'
-
-    DEFAULT_TEST = 'src/test/java'
-
-    def __init__(self, parsed, path):
-        super().__init__(parsed)
-        self._built = False
-        self._root = path.parent
-
-    # Returns (jar_path, plugin)
-    def build_plugin(self, plugin_id, keystore_path, keystore_alias, keystore_password=None):
-        self._big_build(keystore_path, keystore_alias, keystore_password=keystore_password)
-        return self._little_build(plugin_id)
-
-    def get_main(self):
-        return self._parsed.get('main', MavenPluginSet.DEFAULT_MAIN)
-
-    def get_main_path(self):
-        return self.get_root_path().joinpath(self.get_main())
-
-    def get_root(self):
-        return self._root
-
-    def get_root_path(self):
-        return Path(self.get_root()).expanduser().resolve()
-
-    def get_test(self):
-        return self._parsed.get('test', MavenPluginSet.DEFAULT_TEST)
-
-    def get_test_path(self):
-        return self.get_root_path().joinpath(self.get_test())
-
-    def has_plugin(self, plugin_id):
-        return self._plugin_path(plugin_id).is_file()
-
-    def make_plugin(self, plugin_id):
-        return Plugin.from_path(self._plugin_path(plugin_id))
-
-    def _big_build(self, keystore_path, keystore_alias, keystore_password=None):
-        if not self._built:
-            # Do build
-            cmd = ['mvn', 'package',
-                   f'-Dkeystore.file={keystore_path!s}',
-                   f'-Dkeystore.alias={keystore_alias}',
-                   f'-Dkeystore.password={keystore_password}']
-            try:
-                subprocess.run(cmd, cwd=self.get_root_path(), check=True, stdout=sys.stdout, stderr=sys.stderr)
-            except subprocess.CalledProcessError as cpe:
-                raise self._sanitize(cpe)
-            self._built = True
-
-    # Returns (jar_path, plugin)
-    def _little_build(self, plugin_id):
-        jar_path = Path(self.get_root_path(), 'target', 'pluginjars', f'{plugin_id}.jar')
-        if not jar_path.is_file():
-            raise Exception(f'{plugin_id}: built JAR not found: {jar_path!s}')
-        return (jar_path, Plugin.from_jar(jar_path))
-
-    def _plugin_path(self, plugin_id):
-        return Path(self.get_main_path()).joinpath(Plugin.id_to_file(plugin_id))
-
-    def _sanitize(self, called_process_error):
-        cmd = called_process_error.cmd[:]
-        i = 0
-        for i in range(len(cmd)):
-            if cmd[i].startswith('-Dkeystore.password='):
-                cmd[i] = '-Dkeystore.password=<password>'
-        called_process_error.cmd = ' '.join([shlex.quote(c) for c in cmd])
-        return called_process_error
+#: A type alias for plugin set builders, which is the union of
+#: ``MavenPluginSetBuilder`` and ``AntPluginSetBuilder`` using ``type`` as the
+#: discriminator field.
+PluginSetBuilder = Annotated[Union[MavenPluginSetBuilder, AntPluginSetBuilder], Field(discriminator='type')]
+
+
+#: A type alias for the plugin set kind.
+PluginSetKind = Literal['PluginSet']
+
+
+#: A type alias for plugin set identifiers.
+PluginSetIdentifier = str
+
+
+class PluginSet(BaseModel):
+    """
+    A Pydantic model for a plugin set.
+    """
+
+    #: This object's kind.
+    kind: PluginSetKind = Field(title='Kind',
+                                description="This object's kind")
+
+    #: This plugin set's identifier.
+    id: PluginSetIdentifier = Field(title='Plugin Set Identifier',
+                                    description='An identifier for the plugin set')
+
+    #: This plugin set's name.
+    name: str = Field(title='Plugin Set Name',
+                      description='A name for the plugin set')
+
+    #: This plugin set's builder.
+    builder: PluginSetBuilder = Field(title='Plugin Set Builder',
+                                      description='A builder for the plugin set')
+
+    def build_plugin(self,
+                     plugin_id: PluginIdentifier,
+                     keystore_path: Path,
+                     keystore_alias: str,
+                     keystore_password: Optional[Callable[[], str]]=None) -> tuple[Path, Plugin]:
+        """
+        Builds the given plugin with the supplied plugin signing credentials.
+
+        :param plugin_id: A plugin identifier.
+        :type plugin_id: PluginIdentifier
+        :param keystore_path: The path to the plugin signing keystore.
+        :type keystore_path: Path
+        :param keystore_alias: The alias to use in the plugin signing keystore.
+        :type keystore_alias: str
+        :param keystore_password: The plugin signing password.
+        :type keystore_password: Optional[Callable[[], str]]
+        :return: A tuple of the built and signed JAR file and a Plugin object
+                 instantiated from it.
+        """
+        return self.builder.build_plugin(plugin_id, keystore_path, keystore_alias, keystore_password)
+
+    def get_builder(self) -> PluginSetBuilder:
+        """
+        Returns this plugin set's builder.
+
+        :return: This plugin set's builder.
+        :rtype: PluginSetBuilder
+        """
+        return self.builder
+
+    def get_id(self) -> PluginSetIdentifier:
+        """
+        Returns this plugin set's identifier.
+
+        :return: This plugin set's identifier.
+        :rtype: PluginSetIdentifier
+        """
+        return self.id
+
+    def get_name(self) -> str:
+        """
+        Returns this plugin set's name.
+
+        :return: This plugin set's name.
+        :rtype: str
+        """
+        return self.name
+
+    def has_plugin(self,
+                   plugin_id: PluginIdentifier) -> bool:
+        """
+        Determines if the given plugin identifier represents a plugin that is
+        present in the plugin set.
+
+        :param plugin_id: A plugin identifier.
+        :type plugin_id: PluginIdentifier
+        :return: Whether the plugin is present in the plugin set.
+        :rtype: bool
+        """
+        return self.get_builder().has_plugin(plugin_id)
+
+    def initialize(self,
+                   root: Path) -> PluginSet:
+        """
+        Mandatory initialization of the builder.
+
+        :param root: This plugin set's root path.
+        :type root: Path
+        :return: This plugin set, for chaining.
+        :rtype: PluginSet
+        """
+        self.get_builder().initialize(root)
+        return self
+
+    def make_plugin(self,
+                    plugin_id: PluginIdentifier) -> Plugin:
+        """
+        Makes a ``Plugin`` object from the given plugin identifier.
+
+        :param plugin_id: A plugin identifier.
+        :type plugin_id: PluginIdentifier
+        :return: The corresponding ``Plugin`` object.
+        :rtype: Plugin
+        """
+        return self.get_builder().make_plugin(plugin_id)