lockss-turtles 0.6.0.dev20__py3-none-any.whl → 0.6.0.dev22__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-dev22'
 
+#: 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/cli.py

@@ -144,22 +144,18 @@ class PluginJarOptions(BaseModel):
 
 
 class NonInteractiveOptions(BaseModel):
-    non_interactive: Optional[bool] = Field(False, description='(plugin signing credentials) disallow interactive prompts')
+    non_interactive: Optional[bool] = Field(False,
+                                            description='(plugin signing credentials) disallow interactive prompts')
 
 
-class BuildPluginCommand(OutputFormatOptions, NonInteractiveOptions, PluginBuildingOptions, PluginIdentifierOptions):
-    pass
-
-
-class DeployPluginCommand(OutputFormatOptions, NonInteractiveOptions, PluginDeploymentOptions, PluginJarOptions):
-    pass
+class TurtlesCommand(BaseModel):
 
+    class BuildPluginCommand(OutputFormatOptions, NonInteractiveOptions, PluginBuildingOptions, PluginIdentifierOptions): pass
 
-class ReleasePluginCommand(OutputFormatOptions, NonInteractiveOptions, PluginDeploymentOptions, PluginBuildingOptions, PluginIdentifierOptions):
-    pass
+    class DeployPluginCommand(OutputFormatOptions, NonInteractiveOptions, PluginDeploymentOptions, PluginJarOptions): pass
 
+    class ReleasePluginCommand(OutputFormatOptions, NonInteractiveOptions, PluginDeploymentOptions, PluginBuildingOptions, PluginIdentifierOptions): pass
 
-class TurtlesCommand(BaseModel):
     bp: Optional[BuildPluginCommand] = Field(description='synonym for: build-plugin')
     build_plugin: Optional[BuildPluginCommand] = Field(description='build plugins', alias='build-plugin')
     copyright: Optional[StringCommand.type(__copyright__)] = Field(description=COPYRIGHT_DESCRIPTION)
@@ -237,10 +233,10 @@ class TurtlesCli(BaseCli[TurtlesCommand]):
     #     if len(result) > 0:
     #         self._tabulate(title, result, headers)
 
-    def _bp(self, build_plugin_command: BuildPluginCommand) -> None:
+    def _bp(self, build_plugin_command: TurtlesCommand.BuildPluginCommand) -> None:
         return self._build_plugin(build_plugin_command)
 
-    def _build_plugin(self, build_plugin_command: BuildPluginCommand) -> None:
+    def _build_plugin(self, build_plugin_command: TurtlesCommand.BuildPluginCommand) -> None:
         errs = []
         for psc in build_plugin_command.get_plugin_set_catalogs():
             try:
@@ -276,7 +272,7 @@ class TurtlesCli(BaseCli[TurtlesCommand]):
     def _copyright(self, string_command: StringCommand) -> None:
         self._do_string_command(string_command)
 
-    def _deploy_plugin(self, deploy_plugin_command: DeployPluginCommand) -> None:
+    def _deploy_plugin(self, deploy_plugin_command: TurtlesCommand.DeployPluginCommand) -> None:
         errs = []
         for prc in deploy_plugin_command.get_plugin_registry_catalogs():
             try:
@@ -307,7 +303,7 @@ class TurtlesCli(BaseCli[TurtlesCommand]):
     def _do_string_command(self, string_command: StringCommand) -> None:
         string_command()
 
-    def _dp(self, deploy_plugin_command: DeployPluginCommand) -> None:
+    def _dp(self, deploy_plugin_command: TurtlesCommand.DeployPluginCommand) -> None:
         return self._deploy_plugin(deploy_plugin_command)
 
     def _license(self, string_command: StringCommand) -> None:
@@ -322,7 +318,7 @@ class TurtlesCli(BaseCli[TurtlesCommand]):
             self._parser.error('no plugin signing password specified while in non-interactive mode')
         self._app.set_password(lambda: _p)
 
-    def _release_plugin(self, release_plugin_command: ReleasePluginCommand) -> None:
+    def _release_plugin(self, release_plugin_command: TurtlesCommand.ReleasePluginCommand) -> None:
         errs = []
         for psc in release_plugin_command.get_plugin_set_catalogs():
             try:
@@ -371,7 +367,7 @@ class TurtlesCli(BaseCli[TurtlesCommand]):
                                 headers=['Plugin identifier', 'Plugin version', 'Plugin registry', 'Plugin registry layer', 'Deployed JAR'],
                                 tablefmt=release_plugin_command.output_format))
 
-    def _rp(self, release_plugin_command: ReleasePluginCommand) -> None:
+    def _rp(self, release_plugin_command: TurtlesCommand.ReleasePluginCommand) -> None:
         self._release_plugin(release_plugin_command)
 
     def _version(self, string_command: StringCommand) -> None:

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