lockss-turtles 0.6.0.dev17__tar.gz → 0.6.0.dev19__tar.gz

{lockss_turtles-0.6.0.dev17 → lockss_turtles-0.6.0.dev19}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: lockss-turtles
-Version: 0.6.0.dev17
+Version: 0.6.0.dev19
 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-dev1
+.. |RELEASE| replace:: 0.6.0-dev19
 .. |RELEASE_DATE| replace:: ?
 
 .. |HELP| replace:: ``--help/-h``
@@ -54,7 +54,7 @@ Turtles
    :alt: Turtles logo
    :align: right
 
-Turtles is a tool to manage LOCKSS plugin sets and LOCKSS plugin registries.
+Turtles is a command line tool and Python library to manage LOCKSS plugin sets and LOCKSS plugin registries.
 
 **Latest release:** |RELEASE| (|RELEASE_DATE|)
 

{lockss_turtles-0.6.0.dev17 → lockss_turtles-0.6.0.dev19}/README.rst

@@ -2,7 +2,7 @@
 Turtles
 =======
 
-.. |RELEASE| replace:: 0.6.0-dev1
+.. |RELEASE| replace:: 0.6.0-dev19
 .. |RELEASE_DATE| replace:: ?
 
 .. |HELP| replace:: ``--help/-h``
@@ -22,7 +22,7 @@ Turtles
    :alt: Turtles logo
    :align: right
 
-Turtles is a tool to manage LOCKSS plugin sets and LOCKSS plugin registries.
+Turtles is a command line tool and Python library to manage LOCKSS plugin sets and LOCKSS plugin registries.
 
 **Latest release:** |RELEASE| (|RELEASE_DATE|)
 

{lockss_turtles-0.6.0.dev17 → lockss_turtles-0.6.0.dev19}/pyproject.toml

@@ -28,7 +28,7 @@
 
 [project]
 name = "lockss-turtles"
-version = "0.6.0-dev17" # Always change in __init__.py, and at release time in README.rst and CHANGELOG.rst
+version = "0.6.0-dev19" # Always change in __init__.py, and at release time in README.rst and CHANGELOG.rst
 description = "Library and command line tool to manage LOCKSS plugin sets and LOCKSS plugin registries"
 license = { text = "BSD-3-Clause" }
 readme = "README.rst"

{lockss_turtles-0.6.0.dev17 → lockss_turtles-0.6.0.dev19}/src/lockss/turtles/__init__.py

@@ -5,7 +5,7 @@ Library and command line tool to manage LOCKSS plugin sets and LOCKSS plugin
 registries.
 """
 
-__version__ = '0.6.0-dev17'
+__version__ = '0.6.0-dev19'
 
 __copyright__ = '''
 Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University

{lockss_turtles-0.6.0.dev17 → lockss_turtles-0.6.0.dev19}/src/lockss/turtles/__main__.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.
 
+"""
+Entry point for the ``lockss.turtles`` module.
+"""
+
 from lockss.turtles.cli import main
 
 main()

{lockss_turtles-0.6.0.dev17 → lockss_turtles-0.6.0.dev19}/src/lockss/turtles/cli.py

@@ -33,6 +33,7 @@ Tool for managing LOCKSS plugin sets and LOCKSS plugin registries
 """
 
 from getpass import getpass
+from itertools import chain
 from pathlib import Path
 
 from exceptiongroup import ExceptionGroup
@@ -51,7 +52,7 @@ from .util import file_or
 
 
 class PluginBuildingOptions(BaseModel):
-    plugin_set: Optional[list[FilePath]] = Field(aliases=['-s'], description=f'(plugin sets) add one or more plugin sets to the loaded plugin sets')
+    plugin_set: Optional[list[FilePath]] = Field(aliases=['-s'], description=f'(plugin sets) add one or more plugin set definition files to the loaded plugin sets')
     plugin_set_catalog: Optional[list[FilePath]] = Field(aliases=['-S'], description=f'(plugin sets) add one or more plugin set catalogs to the loaded plugin set catalogs; if no plugin set catalogs or plugin sets are specified, load {file_or(TurtlesApp.default_plugin_set_catalog_choices())}')
     plugin_signing_credentials: Optional[FilePath] = Field(aliases=['-c'], description=f'(plugin signing credentials) load the plugin signing credentials from the given file, or if none, from {file_or(TurtlesApp.default_plugin_signing_credentials_choices())}')
     plugin_signing_password: Optional[str] = Field(description='(plugin signing credentials) set the plugin signing password, or if none, prompt interactively')
@@ -97,9 +98,9 @@ class PluginDeploymentOptions(BaseModel):
         raise FileNotFoundError(file_or(TurtlesApp.default_plugin_set_catalog_choices()))
 
     def get_plugin_registry_layers(self) -> list[PluginRegistryLayerIdentifier]:
-        ret = [*(self.plugin_registry_layer or []), *[file_lines(file_path) for file_path in self.plugin_registry_layers or []]]
+        ret = [*(self.plugin_registry_layer or []), *chain.from_iterable(file_lines(file_path) for file_path in self.plugin_registry_layers or [])]
         for layer in reversed(['testing', 'production']):
-            if getattr(self, layer, False):
+            if getattr(self, layer, False) and layer not in ret:
                 ret.insert(0, layer)
         if ret:
             return ret

{lockss_turtles-0.6.0.dev17 → lockss_turtles-0.6.0.dev19}/src/lockss/turtles/plugin_registry.py

@@ -87,7 +87,7 @@ class BasePluginRegistryLayout(BaseModel, ABC):
 
     def get_plugin_registry(self) -> PluginRegistry:
         if self._plugin_registry is None:
-            raise RuntimeError('Uninitialized plugin registry')
+            raise ValueError('Uninitialized plugin registry')
         return self._plugin_registry
 
     def get_type(self) -> PluginRegistryLayoutType:
@@ -194,7 +194,7 @@ class PluginRegistryLayer(BaseModel, ABC):
 
     def get_plugin_registry(self) -> PluginRegistry:
         if self._plugin_registry is None:
-            raise RuntimeError('Uninitialized plugin registry')
+            raise ValueError('Uninitialized plugin registry')
         return self._plugin_registry
 
     def initialize(self, plugin_registry: PluginRegistry) -> PluginRegistryLayer:

{lockss_turtles-0.6.0.dev17 → lockss_turtles-0.6.0.dev19}/src/lockss/turtles/plugin_set.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.
 
+"""
+Representations of plugin sets.
+"""
+
 # 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
@@ -45,63 +49,168 @@ 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(description="This object's kind")
+    #: A non-empty list of plugin set files.
     plugin_set_files: list[str] = Field(min_length=1, description="A non-empty list of plugin set files", title='Plugin Set Files', alias='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
+    ``AntPluginSetBuilder`` and ``MavenPluginSetBuilder``.
+    """
+
+    #: Pydantic definition of the ``type`` field.
     TYPE_FIELD: ClassVar[dict[str, str]] = dict(description='A plugin builder type', title='Plugin Builder Type')
+    #: Pydantic definition of the ``main`` field.
     MAIN_FIELD: ClassVar[dict[str, str]] = dict(description="The path to the plugins' source code, relative to the root of the project", title='Main Code Path')
+    #: Pydantic definition of the ``test`` field.
     TEST_FIELD: ClassVar[dict[str, str]] = dict(description="The path to the plugins' unit tests, relative to the root of the project", title='Test Code Path')
 
     @abstractmethod
     def build_plugin(self, plugin_id: PluginIdentifier, keystore_path: Path, keystore_alias: str, keystore_password=None) -> tuple[Path, Plugin]:
-        pass
+        """
+        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()
 
     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 Plugin.from_path(self._plugin_path(plugin_id))
 
     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 AntPluginSetBuilder(BasePluginSetBuilder):
+    #: 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)
+    #: 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]:
@@ -118,6 +227,9 @@ class AntPluginSetBuilder(BasePluginSetBuilder):
         self._built = False
 
     def _big_build(self) -> None:
+        """
+        Optionally performs the "big build".
+        """
         if not self._built:
             # Do build
             subprocess.run('ant load-plugins',
@@ -125,10 +237,26 @@ class AntPluginSetBuilder(BasePluginSetBuilder):
             self._built = True
 
     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.
+
+        :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: str
+        :return: A tuple of the plugin JAR path and the corresponding ``Plugin``
+                 object.
+        :rtype: tuple[Path, Plugin]
+        """
         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
@@ -211,7 +339,7 @@ class MavenPluginSetBuilder(BasePluginSetBuilder):
     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 Exception(f'{plugin_id}: built JAR not found: {jar_path!s}')
+            raise FileNotFoundError(str(jar_path))
         return jar_path, Plugin.from_jar(jar_path)
 
     def _sanitize(self, called_process_error: subprocess.CalledProcessError) -> subprocess.CalledProcessError:

{lockss_turtles-0.6.0.dev17 → lockss_turtles-0.6.0.dev19}/src/lockss/turtles/util.py

@@ -52,7 +52,7 @@ class BaseModelWithRoot(BaseModel):
 
     def get_root(self) -> Path:
         if self._root is None:
-            raise RuntimeError('Uninitialized root')
+            raise ValueError('Uninitialized root')
         return self._root
 
     def initialize(self, root: PathOrStr) -> BaseModelWithRoot:

{lockss_turtles-0.6.0.dev17 → lockss_turtles-0.6.0.dev19}/tests/unittest/lockss/turtles/test_plugin_set.py

@@ -28,8 +28,13 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 
+from pathlib import Path
+
 from . import PydanticTestCase
-from lockss.turtles.plugin_set import AntPluginSetBuilder, MavenPluginSetBuilder, PluginSet, PluginSetBuilder
+from lockss.turtles.plugin_set import AntPluginSetBuilder, MavenPluginSetBuilder, PluginSet, PluginSetBuilder, PluginSetBuilderType
+
+
+ROOT: Path = Path('.').absolute()
 
 
 class TestPluginSet(PydanticTestCase):
@@ -46,17 +51,27 @@ class TestPluginSet(PydanticTestCase):
         PluginSet(kind='PluginSet', id='myset', name='My Set', builder=AntPluginSetBuilder(type='ant'))
         PluginSet(kind='PluginSet', id='myset', name='My Set', builder=MavenPluginSetBuilder(type='maven'))
 
+
 class TestPluginSetBuilder(PydanticTestCase):
 
-    def doTestPluginSetBuilder(self, Pbsc: type(PluginSetBuilder), typ: str, def_main: str, def_test: str) -> None:
+    def doTestPluginSetBuilder(self, Pbsc: type(PluginSetBuilder), typ: PluginSetBuilderType, def_main: Path, def_test: Path) -> None:
         self.assertPydanticMissing(lambda: Pbsc(), 'type')
         self.assertPydanticLiteralError(lambda: Pbsc(type='BADTYPE'), 'type', typ)
         self.assertIsNone(Pbsc(type=typ)._root)
-        self.assertEqual(Pbsc(type=typ)._get_main(), def_main)
-        self.assertEqual(Pbsc(type=typ, main='mymain')._get_main(), 'mymain')
-        self.assertEqual(Pbsc(type=typ)._get_test(), def_test)
-        self.assertEqual(Pbsc(type=typ, test='mytest')._get_test(), 'mytest')
+        with self.assertRaises(ValueError):
+            Pbsc(type=typ).get_root()
+        self.assertEqual(Pbsc(type=typ).initialize(ROOT).get_root(), ROOT)
+        with self.assertRaises(ValueError):
+            Pbsc(type=typ, main='anything').get_main()
+        self.assertEqual(Pbsc(type=typ).initialize(ROOT).get_main(), def_main)
+        self.assertEqual(Pbsc(type=typ, main='mymain').initialize(ROOT).get_main(), ROOT.joinpath('mymain'))
+        self.assertEqual(Pbsc(type=typ, main='/opt/main').initialize(ROOT).get_main(), Path('/opt/main'))
+        with self.assertRaises(ValueError):
+            Pbsc(type=typ, test='anything').get_test()
+        self.assertEqual(Pbsc(type=typ).initialize(ROOT).get_test(), def_test)
+        self.assertEqual(Pbsc(type=typ, test='mytest').initialize(ROOT).get_test(), ROOT.joinpath('mytest'))
+        self.assertEqual(Pbsc(type=typ, test='/opt/test').initialize(ROOT).get_test(), Path('/opt/test'))
 
     def testPluginSetBuilder(self):
-        self.doTestPluginSetBuilder(AntPluginSetBuilder, 'ant', 'plugins/src', 'plugins/test/src')
-        self.doTestPluginSetBuilder(MavenPluginSetBuilder, 'maven', 'src/main/java', 'src/test/java')
+        self.doTestPluginSetBuilder(AntPluginSetBuilder, 'ant', ROOT.joinpath('plugins/src'), ROOT.joinpath('plugins/test/src'))
+        self.doTestPluginSetBuilder(MavenPluginSetBuilder, 'maven', ROOT.joinpath('src/main/java'), ROOT.joinpath('src/test/java'))