lockss-turtles 0.6.0.dev17__py3-none-any.whl → 0.6.0.dev18__py3-none-any.whl

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-dev18'
 
 __copyright__ = '''
 Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University

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/cli.py

@@ -51,7 +51,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')

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/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,52 +49,149 @@ 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.
+    """
+
+    #: 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 the plugin set's main code path (relative to the root if not
+        absolute).
+
+        :return: The 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 the plugin set's unit test path (relative to the root if not
+        absolute).
+
+        :return: The 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:
+        """
+        Return the concrete implementation's ``main`` field.
+
+        :return: The ``main`` field.
+        :rtype: str
+        """
         return getattr(self, 'main')
 
     def _get_test(self) -> str:
+        """
+        Return 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))
 
 

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.dist-info → lockss_turtles-0.6.0.dev18.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: lockss-turtles
-Version: 0.6.0.dev17
+Version: 0.6.0.dev18
 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-dev18
 .. |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.dev18.dist-info/RECORD

@@ -0,0 +1,15 @@
+lockss/turtles/__init__.py,sha256=l85NQRMGYRq2ptQpR3ssp7sKSXMW-vfL_EZI-mZbjl4,1744
+lockss/turtles/__main__.py,sha256=BqRTG3dejCgLh87UJ1Os9DD9unxnQkOdUQM6eqWS3Sg,1680
+lockss/turtles/app.py,sha256=SAmd_k_2viX_SY2aiXNgQq0k1oPYMUwNBicsnzAo9e4,16689
+lockss/turtles/cli.py,sha256=ZB1H7egHWjG2IkPxwW0NvlLTBQ99bpN5wuzOO7_xa30,20681
+lockss/turtles/plugin.py,sha256=re44YVlzXVU8azDshxn7oHw1GdTQLLQgYwkvZlur-60,5384
+lockss/turtles/plugin_registry.py,sha256=G_CwTFgDV4om1W0-QY7Ww_7mneCbckXuEWMk7ZFOPW4,11916
+lockss/turtles/plugin_set.py,sha256=OCQjRnb4FeIRsuwJpJ63UoXYNeENm39V-iQL47xXZ0M,14711
+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.dev18.dist-info/LICENSE,sha256=O9ONND4uDxY_jucI4jZDf2liAk05ScEJaYu-Al7EOdQ,1506
+lockss_turtles-0.6.0.dev18.dist-info/METADATA,sha256=iyywFL8UvcuqBz6M-T3Vv4AVn8FhtO81nOJCw9biIYU,39692
+lockss_turtles-0.6.0.dev18.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
+lockss_turtles-0.6.0.dev18.dist-info/entry_points.txt,sha256=25BAVFSBRKWAWiXIGZgcr1ypt2mV7nj31Jl8WcNZZOk,51
+lockss_turtles-0.6.0.dev18.dist-info/RECORD,,

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'))

lockss_turtles-0.6.0.dev17.dist-info/RECORD

@@ -1,15 +0,0 @@
-lockss/turtles/__init__.py,sha256=DHr6P3wE_eSUSkgtca783Sm1ppF269jpwUNuxTcaOx4,1744
-lockss/turtles/__main__.py,sha256=825geLIwXS0LKRqxifJXlLaAZrY8nllXfHzw5ch5ysM,1624
-lockss/turtles/app.py,sha256=SAmd_k_2viX_SY2aiXNgQq0k1oPYMUwNBicsnzAo9e4,16689
-lockss/turtles/cli.py,sha256=jKghKNTHmxs0ZKy_R_VVujL6X7Ka1qpC1SmOhObDEfM,20665
-lockss/turtles/plugin.py,sha256=re44YVlzXVU8azDshxn7oHw1GdTQLLQgYwkvZlur-60,5384
-lockss/turtles/plugin_registry.py,sha256=VmvUI6Mx6Jk7fr1L3RfJ4jB6lppCHUm-2PjzwoqxBFk,11920
-lockss/turtles/plugin_set.py,sha256=hKUXOSRyhHxxcMWE3I69Wykod32Ig871oeJsMTvbXfU,11291
-lockss/turtles/util.py,sha256=wGCrw_YySvyqaCzT0PItzXpkLHOCMMC_DQHhGU7zudI,2500
-unittest/lockss/turtles/__init__.py,sha256=hrgWx4GaP-hhPBuRlbLndJnOQmZicKCLaP-dQTCu1sQ,3162
-unittest/lockss/turtles/test_plugin_set.py,sha256=i-VM8mvrPuW2KqUlh2HPVRtgh3-F7RhmRAwcvhwpoDA,3354
-lockss_turtles-0.6.0.dev17.dist-info/LICENSE,sha256=O9ONND4uDxY_jucI4jZDf2liAk05ScEJaYu-Al7EOdQ,1506
-lockss_turtles-0.6.0.dev17.dist-info/METADATA,sha256=RjDZ6rwBmkfoK-d3bsP9LQXsdmd0ZfJhXFmYQRK5nPE,39659
-lockss_turtles-0.6.0.dev17.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-lockss_turtles-0.6.0.dev17.dist-info/entry_points.txt,sha256=25BAVFSBRKWAWiXIGZgcr1ypt2mV7nj31Jl8WcNZZOk,51
-lockss_turtles-0.6.0.dev17.dist-info/RECORD,,