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

lockss/turtles/__init__.py

@@ -5,12 +5,15 @@ Library and command line tool to manage LOCKSS plugin sets and LOCKSS plugin
 registries.
 """
 
-__version__ = '0.6.0-dev20'
+#: This package's version.
+__version__ = '0.6.0-dev21'
 
+#: This package's copyright.
 __copyright__ = '''
 Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
 '''.strip()
 
+#: This package's license.
 __license__ = __copyright__ + '\n\n' + '''
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met:

lockss/turtles/plugin.py

@@ -38,7 +38,7 @@ from __future__ import annotations
 
 from collections.abc import Callable
 from pathlib import Path
-from typing import Any, Optional
+from typing import Any, AnyStr, IO, Optional
 import xml.etree.ElementTree as ET
 from zipfile import ZipFile
 
@@ -48,12 +48,32 @@ from lockss.pybasic.fileutil import path
 from .util import PathOrStr
 
 
+#: A type alias for plugin identifiers.
 PluginIdentifier = str
 
 
 class Plugin(object):
+    """
+    An object to represent a LOCKSS plugin.
+    """
 
-    def __init__(self, plugin_file, plugin_path) -> None:
+    def __init__(self, plugin_file: IO[AnyStr], plugin_path: PathOrStr) -> None:
+        """
+        Constructor.
+
+        Other exceptions than ``RuntimeError`` may be raised if the plugin
+        definition file cannot be parsed by ``xml.etree.ElementTree``.
+
+        :param plugin_file: An open file-like object that can read the plugin
+                            definition file.
+        :type plugin_file: IO[AnyStr]
+        :param plugin_path: A string (or Path) representing the hierarchical
+                            path of the plugin definition file (as a real file,
+                            or as a file entry in a JAR file).
+        :type plugin_path: PathOrStr
+        :raises RuntimeError: If the plugin definition file parses as XML but
+                              the top-level element is not <map>.
+        """
         super().__init__()
         self._path = plugin_path
         self._parsed = ET.parse(plugin_file).getroot()
@@ -62,6 +82,14 @@ class Plugin(object):
             raise RuntimeError(f'{plugin_path!s}: invalid root element: {tag}')
 
     def get_aux_packages(self) -> list[str]:
+        """
+        Returns the (possibly empty) list of auxiliary code packages declared by
+        the plugin (``plugin_aux_packages``).
+
+        :return: A non-null list of strings representing auxiliary code
+                 packages.
+        :rtype: list[str]
+        """
         key = 'plugin_aux_packages'
         lst = [x[1] for x in self._parsed.findall('entry') if x[0].tag == 'string' and x[0].text == key]
         if lst is None or len(lst) < 1:
@@ -71,21 +99,76 @@ class Plugin(object):
         return [x.text for x in lst[0].findall('string')]
 
     def get_identifier(self) -> Optional[PluginIdentifier]:
+        """
+        Get this plugin's identifier (``plugin_identifier``).
+
+        :return: A plugin identifier, or None if missing.
+        :rtype: Optional[PluginIdentifier]
+        :raises ValueError: If the plugin definition contains more than one.
+        """
         return self._only_one('plugin_identifier')
 
     def get_name(self) -> Optional[str]:
+        """
+        Get this plugin's name (``plugin_name``).
+
+        :return: A plugin name, or None if missing.
+        :rtype: Optional[str]
+        :raises ValueError: If the plugin definition contains more than one.
+        """
         return self._only_one('plugin_name')
 
     def get_parent_identifier(self) -> Optional[PluginIdentifier]:
+        """
+        Get this plugin's parent identifier (``plugin_parent``).
+
+        :return: A parent plugin identifier, or None if this plugin has no
+                 parent.
+        :rtype: Optional[PluginIdentifier]
+        :raises ValueError: If the plugin definition contains more than one.
+        """
         return self._only_one('plugin_parent')
 
     def get_parent_version(self) -> Optional[int]:
+        """
+        Get this plugin's parent version (``plugin_parent_version``).
+
+        :return: A parent plugin version, or None if this plugin has no
+                 parent.
+        :rtype: Optional[int]
+        :raises ValueError: If the plugin definition contains more than one.
+        """
         return self._only_one('plugin_parent_version', int)
 
     def get_version(self) -> Optional[int]:
+        """
+        Get this plugin's version (``plugin_version``).
+
+        :return: A plugin version, or None if missing.
+        :rtype: Optional[int]
+        :raises ValueError: If the plugin definition contains more than one.
+        """
         return self._only_one('plugin_version', int)
 
-    def _only_one(self, key: str, result: Callable=str) -> Optional[Any]:
+    def _only_one(self, key: str, result: Callable[[str], Any]=str) -> Optional[Any]:
+        """
+        Retrieves the value of a given key in the plugin definition, optionally
+        coerced into a representation (by default simply a string).
+
+        :param key: A plugin key.
+        :param key: str
+        :param result: A functor that takes a string and returns the desired
+                       representation; by default this is the string constructor
+                       ``str``, meaning by default the string values are
+                       returned unchanged.
+        :param result: Callable[[str], Any]
+        :return: The value for the given key, coerced through the given functor,
+                 or None if the plugin definition does not contain any entry
+                 with the given key.
+        :rtype: Optional[Any]
+        :raises ValueError: If the plugin definition contains more than one
+                            entry with the given key.
+        """
         lst = [x[1].text for x in self._parsed.findall('entry') if x[0].tag == 'string' and x[0].text == key]
         if lst is None or len(lst) < 1:
             return None
@@ -94,8 +177,16 @@ class Plugin(object):
         return result(lst[0])
 
     @staticmethod
-    def from_jar(jar_path: PathOrStr) -> Plugin:
-        jar_path = path(jar_path)  # in case it's a string
+    def from_jar(jar_path_or_str: PathOrStr) -> Plugin:
+        """
+        Instantiates a Plugin object from the given plugin JAR file.
+
+        :param jar_path_or_str: The path to a plugin JAR.
+        :type jar_path_or_str: PathOrStr
+        :return: A Plugin object.
+        :rtype: Plugin
+        """
+        jar_path = path(jar_path_or_str)
         plugin_id = Plugin.id_from_jar(jar_path)
         plugin_fstr = str(Plugin.id_to_file(plugin_id))
         with ZipFile(jar_path, 'r') as zip_file:
@@ -103,18 +194,50 @@ class Plugin(object):
                 return Plugin(plugin_file, plugin_fstr)
 
     @staticmethod
-    def from_path(fpath: PathOrStr) -> Plugin:
-        fpath = path(fpath)  # in case it's a string
-        with open(fpath, 'r') as input_file:
+    def from_path(path_or_str: PathOrStr) -> Plugin:
+        """
+        Instantiates a Plugin object from the given plugin file.
+
+        :param path_or_str: The path to a plugin file.
+        :type path_or_str: PathOrStr
+        :return: A Plugin object.
+        :rtype: Plugin
+        """
+        fpath = path(path_or_str)
+        with fpath.open('r') as input_file:
             return Plugin(input_file, fpath)
 
     @staticmethod
     def file_to_id(plugin_fstr: str) -> PluginIdentifier:
+        """
+        Converts a plugin file path (ending in ``.xml``) to the implied plugin
+        identifier (e.g. ``org/myproject/plugin/MyPlugin.xml`` implies
+        ``org.myproject.plugin.MyPlugin``).
+
+        See also ``id_to_file``.
+
+        :param plugin_fstr: A string file path.
+        :type plugin_fstr: str
+        :return: A plugin identifier.
+        :rtype: PluginIdentifier
+        """
         return plugin_fstr.replace('/', '.')[:-4]  # 4 is len('.xml')
 
     @staticmethod
-    def id_from_jar(jar_path: PathOrStr) -> PluginIdentifier:
-        jar_path = path(jar_path)  # in case it's a string
+    def id_from_jar(jar_path_or_str: PathOrStr) -> PluginIdentifier:
+        """
+        Extracts the plugin identifier from a plugin JAR's manifest file.
+
+        :param jar_path_or_str: The path to a plugin JAR.
+        :type jar_path_or_str: PathOrStr
+        :return: The plugin identifier extracted from the given plugin JAR's
+                 manifest file.
+        :rtype: PluginIdentifier
+        :raises Exception: If the JAR's manifest file has no entry with
+                           ``Lockss-Plugin`` equal to ``true`` and ``Name``
+                           equal to the packaged plugin's identifier.
+        """
+        jar_path = path(jar_path_or_str)
         manifest = java_manifest.from_jar(jar_path)
         for entry in manifest:
             if entry.get('Lockss-Plugin') == 'true':
@@ -127,8 +250,29 @@ class Plugin(object):
 
     @staticmethod
     def id_to_dir(plugin_id: PluginIdentifier) -> Path:
+        """
+        Returns the path of the directory containing the given plugin identifier
+        (for example ``org/myproject/plugin`` for
+        ``org.myproject.plugin.MyPlugin``).
+
+        :param plugin_id: A plugin identifier.
+        :type plugin_id: PluginIdentifier
+        :return: The directory path containing the given plugin identifier.
+        :rtype: Path
+        """
         return Plugin.id_to_file(plugin_id).parent
 
     @staticmethod
     def id_to_file(plugin_id: PluginIdentifier) -> Path:
+        """
+        Returns the path of the definition file corresponding to the given
+        plugin identifier (for example ``org/myproject/plugin/MyPlugin.xml`` for
+        ``org.myproject.plugin.MyPlugin``).
+
+        :param plugin_id: A plugin identifier.
+        :type plugin_id: PluginIdentifier
+        :return: The path of the definition file corresponding to the given
+                 plugin identifier.
+        :rtype: Path
+        """
         return Path(f'{plugin_id.replace(".", "/")}.xml')

lockss/turtles/plugin_registry.py

@@ -45,13 +45,12 @@ from .plugin import Plugin, PluginIdentifier
 from .util import BaseModelWithRoot
 
 
-
 PluginRegistryCatalogKind = Literal['PluginRegistryCatalog']
 
 
 class PluginRegistryCatalog(BaseModelWithRoot):
-    kind: PluginRegistryCatalogKind = Field(description="This object's kind")
-    plugin_registry_files: list[str] = Field(min_length=1, description="A non-empty list of plugin registry files", title='Plugin Registry Files', alias='plugin-registry-files')
+    kind: PluginRegistryCatalogKind = Field(title='Kind', description="This object's kind")
+    plugin_registry_files: list[str] = Field(alias='plugin-registry-files', min_length=1, title='Plugin Registry Files', description="A non-empty list of plugin registry files")
 
     def get_plugin_registry_files(self) -> list[Path]:
         return [self.get_root().joinpath(pstr) for pstr in self.plugin_registry_files]

lockss/turtles/plugin_set.py

@@ -86,11 +86,11 @@ class BasePluginSetBuilder(BaseModelWithRoot, ABC):
     """
 
     #: Pydantic definition of the ``type`` field.
-    TYPE_FIELD: ClassVar[dict[str, str]] = dict(description='A plugin builder type', title='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(description="The path to the plugins' source code, relative to the root of the project", title='Main Code Path')
+    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(description="The path to the plugins' unit tests, relative to the root of the project", title='Test Code Path')
+    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]:
@@ -361,10 +361,10 @@ PluginSetIdentifier = str
 
 
 class PluginSet(BaseModel):
-    kind: PluginSetKind = Field(description="This object's kind")
-    id: PluginSetIdentifier = Field(description='An identifier for the plugin set')
-    name: str = Field(description='A name for the plugin set')
-    builder: PluginSetBuilder = Field(description='A builder for the plugin set', title='Plugin Set Builder')
+    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')
 
     def build_plugin(self, plugin_id: PluginIdentifier, keystore_path: Path, keystore_alias: str, keystore_password=None) -> tuple[Path, Plugin]:
         return self.builder.build_plugin(plugin_id, keystore_path, keystore_alias, keystore_password)

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: lockss-turtles
-Version: 0.6.0.dev20
+Version: 0.6.0.dev21
 Summary: Library and command line tool to manage LOCKSS plugin sets and LOCKSS plugin registries
 License: BSD-3-Clause
 Author: Thib Guicherd-Callin

lockss_turtles-0.6.0.dev21.dist-info/RECORD

@@ -0,0 +1,15 @@
+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,,

lockss_turtles-0.6.0.dev20.dist-info/RECORD

@@ -1,15 +0,0 @@
-lockss/turtles/__init__.py,sha256=6c7aKfAeWBtkUI7Wkxha25Uo07VDn4hinKMzDi_Z47Q,1744
-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=re44YVlzXVU8azDshxn7oHw1GdTQLLQgYwkvZlur-60,5384
-lockss/turtles/plugin_registry.py,sha256=yyfTtB0yvWpBXYTSklroo0igdcLrUojjlpzPGxielAQ,11930
-lockss/turtles/plugin_set.py,sha256=pYggWJ6JakL3NYCvdmbxFAaZ-1pWJTZ_CRW-tUxPVQk,15828
-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.dev20.dist-info/LICENSE,sha256=O9ONND4uDxY_jucI4jZDf2liAk05ScEJaYu-Al7EOdQ,1506
-lockss_turtles-0.6.0.dev20.dist-info/METADATA,sha256=egDTHpN4pmE9U6o8wmwaguwAMn9IwOp3ozofufZxgEk,39692
-lockss_turtles-0.6.0.dev20.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-lockss_turtles-0.6.0.dev20.dist-info/entry_points.txt,sha256=25BAVFSBRKWAWiXIGZgcr1ypt2mV7nj31Jl8WcNZZOk,51
-lockss_turtles-0.6.0.dev20.dist-info/RECORD,,