lockss-turtles 0.6.0.dev21__py3-none-any.whl → 0.6.0.dev22__py3-none-any.whl

lockss/turtles/plugin_set.py

@@ -29,7 +29,7 @@
 # POSSIBILITY OF SUCH DAMAGE.
 
 """
-Representations of plugin sets.
+Library to represent plugin sets and plugin set catalogs.
 """
 
 # Remove in Python 3.14
@@ -49,6 +49,7 @@ 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']
 
@@ -58,10 +59,16 @@ 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")
+    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")
+    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]:
         """
@@ -82,18 +89,27 @@ class BasePluginSetBuilder(BaseModelWithRoot, ABC):
     """
     An abstract Pydantic model (``lockss.turtles.util.BaseModelWithRoot``) to
     represent a plugin set builder, with concrete implementations
-    ``AntPluginSetBuilder`` and ``MavenPluginSetBuilder``.
+    ``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')
+    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")
+    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")
+    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]:
+    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.
 
@@ -143,7 +159,8 @@ class BasePluginSetBuilder(BaseModelWithRoot, ABC):
         """
         return getattr(self, 'type')
 
-    def has_plugin(self, plugin_id: PluginIdentifier) -> bool:
+    def has_plugin(self,
+                   plugin_id: PluginIdentifier) -> bool:
         """
         Determines if the given plugin identifier represents a plugin that is
         present in the plugin set.
@@ -155,7 +172,8 @@ class BasePluginSetBuilder(BaseModelWithRoot, ABC):
         """
         return self._plugin_path(plugin_id).is_file()
 
-    def make_plugin(self, plugin_id: PluginIdentifier) -> Plugin:
+    def make_plugin(self,
+                    plugin_id: PluginIdentifier) -> Plugin:
         """
         Makes a ``Plugin`` object from the given plugin identifier.
 
@@ -184,7 +202,8 @@ class BasePluginSetBuilder(BaseModelWithRoot, ABC):
         """
         return getattr(self, 'test')
 
-    def _plugin_path(self, plugin_id: PluginIdentifier) -> Path:
+    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.
@@ -197,23 +216,188 @@ class BasePluginSetBuilder(BaseModelWithRoot, ABC):
         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: Optional[str] = Field(DEFAULT_MAIN,
+                                **BasePluginSetBuilder.MAIN_FIELD)
+
+    #: This plugin set builder's unit test path.
+    test: Optional[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=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 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
+
+    def _big_build(self,
+                   keystore_path: Path,
+                   keystore_alias: str,
+                   keystore_password: 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:
+        :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}',
+                   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
+
+    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)
+
+    def _sanitize(self,
+                  called_process_error: subprocess.CalledProcessError) -> subprocess.CalledProcessError:
+        """
+        Alters the ``-Dkeystore.password=`` portion of a called process error.
+
+        :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
+
+
 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: Optional[str] = Field(DEFAULT_MAIN, **BasePluginSetBuilder.MAIN_FIELD)
+    main: Optional[str] = Field(DEFAULT_MAIN,
+                                **BasePluginSetBuilder.MAIN_FIELD)
+
     #: This plugin set builder's unit test path.
-    test: Optional[str] = Field(DEFAULT_TEST, **BasePluginSetBuilder.TEST_FIELD)
+    test: Optional[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=None) -> tuple[Path, Plugin]:
+    def build_plugin(self,
+                     plugin_id: PluginIdentifier,
+                     keystore_path: Path,
+                     keystore_alias: str,
+                     keystore_password=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 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')
@@ -222,13 +406,22 @@ class AntPluginSetBuilder(BasePluginSetBuilder):
         # Little build
         return self._little_build(plugin_id, keystore_path, keystore_alias, keystore_password=keystore_password)
 
-    def model_post_init(self, context: Any) -> None:
+    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
 
     def _big_build(self) -> None:
         """
-        Optionally performs the "big build".
+        Runs ``ant load-plugins`` if the ``_built`` flag is False.
+
+        :raises subprocess.CalledProcessError: If a subprocess fails.
         """
         if not self._built:
             # Do build
@@ -236,7 +429,11 @@ class AntPluginSetBuilder(BasePluginSetBuilder):
                            shell=True, cwd=self.get_root(), check=True, stdout=sys.stdout, stderr=sys.stderr)
             self._built = True
 
-    def _little_build(self, plugin_id: PluginIdentifier, keystore_path: Path, keystore_alias: str, keystore_password: str=None) -> tuple[Path, Plugin]:
+    def _little_build(self,
+                      plugin_id: PluginIdentifier,
+                      keystore_path: Path,
+                      keystore_alias: str,
+                      keystore_password: str=None) -> tuple[Path, Plugin]:
         """
         Performs the "little build" of the given plugin.
 
@@ -244,14 +441,17 @@ class AntPluginSetBuilder(BasePluginSetBuilder):
         :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.
+        :param keystore_alias: The alias to use in the plugin signing keystore.
         :type keystore_alias: str
-        :param keystore_password: The signing password.
-        :type keystore_password: str
-        :return: A tuple of the plugin JAR path and the corresponding ``Plugin``
-                 object.
+        :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.
         """
         orig_plugin = None
         cur_id = plugin_id
@@ -296,7 +496,15 @@ class AntPluginSetBuilder(BasePluginSetBuilder):
     # def _plugin_path(self, plugin_id: PluginIdentifier) -> Path:
     #     return self.get_main().joinpath(Plugin.id_to_file(plugin_id))
 
-    def _sanitize(self, called_process_error: subprocess.CalledProcessError) -> subprocess.CalledProcessError:
+    def _sanitize(self,
+                  called_process_error: subprocess.CalledProcessError) -> subprocess.CalledProcessError:
+        """
+        Alters the value of ``--password`` in a 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[:]
         for i in range(1, len(cmd)):
             if cmd[i - 1] == '--password':
@@ -305,85 +513,123 @@ class AntPluginSetBuilder(BasePluginSetBuilder):
         return called_process_error
 
 
-class MavenPluginSetBuilder(BasePluginSetBuilder):
-    DEFAULT_MAIN: ClassVar[str] = 'src/main/java'
-    DEFAULT_TEST: ClassVar[str] = 'src/test/java'
-
-    type: Literal['maven'] = Field(**BasePluginSetBuilder.TYPE_FIELD)
-    main: Optional[str] = Field(DEFAULT_MAIN, **BasePluginSetBuilder.MAIN_FIELD)
-    test: Optional[str] = Field(DEFAULT_TEST, **BasePluginSetBuilder.TEST_FIELD)
-
-    _built: bool
-
-    def build_plugin(self, plugin_id: PluginIdentifier, keystore_path: Path, keystore_alias: str, keystore_password=None) -> tuple[Path, Plugin]:
-        self._big_build(keystore_path, keystore_alias, keystore_password=keystore_password)
-        return self._little_build(plugin_id)
-
-    def model_post_init(self, context: Any) -> None:
-        super().model_post_init(context)
-        self._built = False
-
-    def _big_build(self, keystore_path: Path, keystore_alias: str, keystore_password: str=None) -> 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(), check=True, stdout=sys.stdout, stderr=sys.stderr)
-            except subprocess.CalledProcessError as cpe:
-                raise self._sanitize(cpe)
-            self._built = True
-
-    def _little_build(self, plugin_id: PluginIdentifier) -> tuple[Path, Plugin]:
-        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)
-
-    def _sanitize(self, called_process_error: subprocess.CalledProcessError) -> subprocess.CalledProcessError:
-        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
-
-
-PluginSetBuilder = Annotated[Union[AntPluginSetBuilder, MavenPluginSetBuilder], Field(discriminator='type')]
+#: 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):
-    kind: PluginSetKind = Field(title='Kind', description="This object's kind")
-    id: PluginSetIdentifier = Field(title='Plugin Set Identifier', description='An identifier for the plugin set')
-    name: str = Field(title='Plugin Set Name', description='A name for the plugin set')
-    builder: PluginSetBuilder = Field(title='Plugin Set Builder', description='A builder for the plugin set')
+    """
+    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=None) -> tuple[Path, Plugin]:
+        """
+        Builds the given plugin with the supplied plugin signing credentials.
 
-    def build_plugin(self, plugin_id: PluginIdentifier, keystore_path: Path, keystore_alias: str, keystore_password=None) -> tuple[Path, 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:
+        :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:
+    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:
+    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:
+    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)

lockss/turtles/util.py

@@ -28,6 +28,10 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 
+"""
+Utilities for the ``lockss.turtles`` package.
+"""
+
 # Remove in Python 3.14
 # See https://stackoverflow.com/questions/33533148/how-do-i-type-hint-a-method-with-the-type-of-the-enclosing-class/33533514#33533514
 from __future__ import annotations
@@ -40,25 +44,62 @@ from lockss.pybasic.fileutil import path
 from pydantic import BaseModel
 
 
-# Candidate for lockss-pybasic
+#: Type alias for the union of ``Path`` and ``str``.
 PathOrStr = Union[Path, str]
 
 
 class BaseModelWithRoot(BaseModel):
+    """
+    A Pydantic model with a root path which can be used to resolve relative
+    paths.
+    """
+
+    #: An internal root path.
     _root: Optional[Path]
 
     def model_post_init(self, context: Any) -> None:
+        """
+        Pydantic post-initialization method to create the ``_root`` field.
+        """
         self._root = None
 
     def get_root(self) -> Path:
+        """
+        Returns this object's root path.
+
+        See ``initialize``.
+
+        :return: This object's root path.
+        :rtype: Path
+        :raises ValueError: If this object's ``initialize`` method was not
+                            called.
+        """
         if self._root is None:
             raise ValueError('Uninitialized root')
         return self._root
 
-    def initialize(self, root: PathOrStr) -> BaseModelWithRoot:
-        self._root = path(root)
+    def initialize(self,
+                   root_path_or_str: PathOrStr) -> BaseModelWithRoot:
+        """
+        Mandatory initialization of the root path.
+
+        :param root_path_or_str: This object's root path.
+        :type root_path_or_str: PathOrStr
+        :return: This object, for chaining.
+        :rtype: BaseModelWithRoot
+        """
+        self._root = path(root_path_or_str)
         return self
 
 
 def file_or(paths: Iterable[Path]) -> str:
+    """
+    Turns an iterable of file paths and returns them as a ``" or "``-separated
+    string.
+
+    :param paths: A non-null list of file paths.
+    :type paths: Iterable[Path]
+    :return: A ``" or "``-separated string of the given file paths.
+    :rtype: str
+    """
     return ' or '.join(map(str, paths))

{lockss_turtles-0.6.0.dev21.dist-info → lockss_turtles-0.6.0.dev22.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: lockss-turtles
-Version: 0.6.0.dev21
+Version: 0.6.0.dev22
 Summary: Library and command line tool to manage LOCKSS plugin sets and LOCKSS plugin registries
 License: BSD-3-Clause
 Author: Thib Guicherd-Callin
@@ -34,7 +34,7 @@ Description-Content-Type: text/x-rst
 Turtles
 =======
 
-.. |RELEASE| replace:: 0.6.0-dev20
+.. |RELEASE| replace:: 0.6.0-dev22
 .. |RELEASE_DATE| replace:: ?
 
 .. |HELP| replace:: ``--help/-h``

lockss_turtles-0.6.0.dev22.dist-info/RECORD

@@ -0,0 +1,15 @@
+lockss/turtles/__init__.py,sha256=v-2mPurnlbDsfTo_37mD7fnqclC3pS8DScu46ZawpcQ,1827
+lockss/turtles/__main__.py,sha256=BqRTG3dejCgLh87UJ1Os9DD9unxnQkOdUQM6eqWS3Sg,1680
+lockss/turtles/app.py,sha256=Rxbsq10A830D1r99a5tqLVYWM3bJZ2Org-JKjXD-2Mk,16689
+lockss/turtles/cli.py,sha256=Pgd0GSThxDfnPWKwwujo6ZocfKePoe-aiHJ9qYpm9BQ,21019
+lockss/turtles/plugin.py,sha256=HT01Er9-odvJ4lF8DNC7TV4uxSqTw44UBe02Jgj5xMs,11065
+lockss/turtles/plugin_registry.py,sha256=UlB9faNH8fEh9mfdj6byMcRcZ7axi0DzUP2qdyj9ANk,26935
+lockss/turtles/plugin_set.py,sha256=PuzSWl2k7ikbkKtxStQRJhcXi1JXuSBl9jXz4dzp7Ts,24550
+lockss/turtles/util.py,sha256=kETdjOSDaECs2xSm6ah8UoPVuoo42eFUJEEJn5wqYXE,3647
+unittest/lockss/turtles/__init__.py,sha256=hrgWx4GaP-hhPBuRlbLndJnOQmZicKCLaP-dQTCu1sQ,3162
+unittest/lockss/turtles/test_plugin_set.py,sha256=q6JmooDR-wijAQ8x9DWKTNB6Of4EOr3Dgq8oaX0LTpQ,4179
+lockss_turtles-0.6.0.dev22.dist-info/LICENSE,sha256=O9ONND4uDxY_jucI4jZDf2liAk05ScEJaYu-Al7EOdQ,1506
+lockss_turtles-0.6.0.dev22.dist-info/METADATA,sha256=jgCvdNmmsDAzEDTGldk4MfLGRlq8tHfhvh-Bpilr4JQ,39692
+lockss_turtles-0.6.0.dev22.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+lockss_turtles-0.6.0.dev22.dist-info/entry_points.txt,sha256=25BAVFSBRKWAWiXIGZgcr1ypt2mV7nj31Jl8WcNZZOk,51
+lockss_turtles-0.6.0.dev22.dist-info/RECORD,,

lockss_turtles-0.6.0.dev21.dist-info/RECORD

@@ -1,15 +0,0 @@
-lockss/turtles/__init__.py,sha256=9arhPOwCemb5EemdFE4gisbpLEE6bPqOBGi1yOXJmIA,1827
-lockss/turtles/__main__.py,sha256=BqRTG3dejCgLh87UJ1Os9DD9unxnQkOdUQM6eqWS3Sg,1680
-lockss/turtles/app.py,sha256=Rxbsq10A830D1r99a5tqLVYWM3bJZ2Org-JKjXD-2Mk,16689
-lockss/turtles/cli.py,sha256=ZijrjwW1VXtmRvTDpfLnLvq9aL0CfK-F6mglk04RihI,20887
-lockss/turtles/plugin.py,sha256=HT01Er9-odvJ4lF8DNC7TV4uxSqTw44UBe02Jgj5xMs,11065
-lockss/turtles/plugin_registry.py,sha256=ZGlVnhP831hmqLQ9cJueUAXlZWQ67rm0cs6U91F7STc,11943
-lockss/turtles/plugin_set.py,sha256=Q-d-UfZM8I6f-z4TeYe8jdBbhPv0r4ro2H24oNd8Syc,15898
-lockss/turtles/util.py,sha256=8EyWvzTLNycQM_ZKCtWm8FpKJSrwaCSWh8006UYq6vU,2498
-unittest/lockss/turtles/__init__.py,sha256=hrgWx4GaP-hhPBuRlbLndJnOQmZicKCLaP-dQTCu1sQ,3162
-unittest/lockss/turtles/test_plugin_set.py,sha256=q6JmooDR-wijAQ8x9DWKTNB6Of4EOr3Dgq8oaX0LTpQ,4179
-lockss_turtles-0.6.0.dev21.dist-info/LICENSE,sha256=O9ONND4uDxY_jucI4jZDf2liAk05ScEJaYu-Al7EOdQ,1506
-lockss_turtles-0.6.0.dev21.dist-info/METADATA,sha256=2HRA5jwOYJaTyU4wXqaIBzQg4aKlxdjTdl9lqL3aT9w,39692
-lockss_turtles-0.6.0.dev21.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-lockss_turtles-0.6.0.dev21.dist-info/entry_points.txt,sha256=25BAVFSBRKWAWiXIGZgcr1ypt2mV7nj31Jl8WcNZZOk,51
-lockss_turtles-0.6.0.dev21.dist-info/RECORD,,