lockss-turtles 0.6.0.dev24__py3-none-any.whl → 0.6.0.dev25__py3-none-any.whl

lockss/turtles/__init__.py

@@ -6,7 +6,7 @@ registries.
 """
 
 #: This package's version.
-__version__ = '0.6.0-dev24'
+__version__ = '0.6.0-dev25'
 
 #: This package's copyright.
 __copyright__ = '''

lockss/turtles/app.py

@@ -28,80 +28,156 @@
 # ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 # POSSIBILITY OF SUCH DAMAGE.
 
-# 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
+"""
+Module to represent Turtles operations.
+"""
+
+# Remove in Python 3.14; see https://stackoverflow.com/a/33533514
 from __future__ import annotations
 
+# Remove in Python 3.11; see https://docs.python.org/3.11/library/exceptions.html#exception-groups
+from exceptiongroup import ExceptionGroup
+
 from collections.abc import Callable, Iterable
 from pathlib import Path
-from typing import ClassVar, Literal, Optional, Union
+from typing import ClassVar, Optional, Union
 
-from exceptiongroup import ExceptionGroup
 from lockss.pybasic.fileutil import path
-from pydantic import Field, ValidationError
+from pydantic import ValidationError
 import xdg
 import yaml
 
 from .plugin import Plugin, PluginIdentifier
-from .plugin_registry import PluginRegistry, PluginRegistryCatalog, PluginRegistryCatalogKind, PluginRegistryKind, PluginRegistryLayerIdentifier
+from .plugin_registry import PluginRegistry, PluginRegistryCatalog, PluginRegistryCatalogKind, PluginRegistryIdentifier, PluginRegistryKind, PluginRegistryLayerIdentifier
 from .plugin_set import PluginSet, PluginSetCatalog, PluginSetCatalogKind, PluginSetKind
-from .util import BaseModelWithRoot, PathOrStr
+from .plugin_signing_credentials import PluginSigningCredentials, PluginSigningCredentialsKind
+from .util import PathOrStr
 
 
+#: Type alias for the result of a single plugin building operation.
+#: First item (index 0): identifier of the plugin set that had the given plugin.
+#: Second item (index 1): plugin JAR file path (or None if not built).
+#: Third item (index 2): plugin object (or None if not built).
+BuildPluginResult = tuple[str, Optional[Path], Optional[Plugin]]
 
-PluginSigningCredentialsKind = Literal['PluginSigningCredentials']
 
+#: Type alias for the result of a single plugin deployment operation to a given
+#: plugin registry layer.
+#: First item (index 0):
+#: Second item (index 1):
+#: Third item (index 2): deployed JAR file path (or None if not deployed).
+#: Fourth item (index 3): plugin object (or None if not deployed).
+DeployPluginResult = tuple[PluginRegistryIdentifier, PluginRegistryLayerIdentifier, Optional[Path], Optional[Plugin]]
 
-class PluginSigningCredentials(BaseModelWithRoot):
-    kind: PluginSigningCredentialsKind = Field(description="This object's kind")
-    plugin_signing_keystore: str = Field(title='Plugin Signing Keystore', description='A path to the plugin signing keystore', alias='plugin-signing-keystore')
-    plugin_signing_alias: str = Field(title='Plugin Signing Alias', description='The plugin signing alias to use', alias='plugin-signing-alias')
 
-    def get_plugin_signing_alias(self) -> str:
-        return self.plugin_signing_alias
-
-    def get_plugin_signing_keystore(self) -> Path:
-        return self.get_root().joinpath(self.plugin_signing_keystore)
-
-
-class TurtlesApp(object):
+class Turtles(object):
+    """
+    A Turtles command object, which can be used to execute Turtles operations.
+    """
 
+    #: The name of a Turtles configuration directory.
     CONFIG_DIR_NAME: ClassVar[str] = 'lockss-turtles'
 
+    #: The Turtles configuration directory under ``$XDG_CONFIG_HOME`` (by
+    # default ``$HOME/.config``, which is typically ``/home/$USER/.config``).
     XDG_CONFIG_DIR: ClassVar[Path] = Path(xdg.xdg_config_home(), CONFIG_DIR_NAME)
 
-    USR_CONFIG_DIR: ClassVar[Path] = Path('/usr/local/share', CONFIG_DIR_NAME)
-
+    #: The Turtles configuration directory under ``/etc``.
     ETC_CONFIG_DIR: ClassVar[Path] = Path('/etc', CONFIG_DIR_NAME)
 
+    #: The Turtles configuration directory under ``/usr/local/share``.
+    USR_CONFIG_DIR: ClassVar[Path] = Path('/usr/local/share', CONFIG_DIR_NAME)
+
+    #: The Turtles configuration directories in order of preference:
+    #: ``XDG_CONFIG_DIR``, ``ETC_CONFIG_DIR``, ``USR_CONFIG_DIR``
     CONFIG_DIRS: ClassVar[tuple[Path, ...]] = (XDG_CONFIG_DIR, ETC_CONFIG_DIR, USR_CONFIG_DIR)
 
+    #: The default plugin registry catalog file name.
     PLUGIN_REGISTRY_CATALOG: ClassVar[str] = 'plugin-registry-catalog.yaml'
 
+    #: The default plugin set catalog file name.
     PLUGIN_SET_CATALOG: ClassVar[str] = 'plugin-set-catalog.yaml'
 
+    #: The default plugin signing credentials file name.
     PLUGIN_SIGNING_CREDENTIALS: ClassVar[str] = 'plugin-signing-credentials.yaml'
 
     def __init__(self) -> None:
+        """
+        Constructor.
+        """
         super().__init__()
-        self._password: Optional[Callable[[], str]] = None
+        self._plugin_signing_password_callable: Optional[Callable[[], str]] = None
         self._plugin_registries: list[PluginRegistry] = list()
         self._plugin_registry_catalogs: list[PluginRegistryCatalog] = list()
         self._plugin_set_catalogs: list[PluginSetCatalog] = list()
         self._plugin_sets: list[PluginSet] = list()
         self._plugin_signing_credentials: Optional[PluginSigningCredentials] = None
 
-    def build_plugin(self, plugin_ids: list[PluginIdentifier]) -> dict[str, tuple[str, Path, Plugin]]:
+    def build_plugin(self,
+                     plugin_id_or_plugin_ids: Union[PluginIdentifier, list[PluginIdentifier]]) -> dict[str, BuildPluginResult]:
+        """
+        Builds zero or more plugins.
+
+        :param plugin_id_or_plugin_ids: Either one plugin identifier, or a list
+                                        of plugin identifiers.
+        :type plugin_id_or_plugin_ids: Union[PluginIdentifier, list[PluginIdentifier]]
+        :return: A mapping from plugin identifier to build plugin result; if no
+                 plugin identifiers were given, the result is an empty mapping.
+        :rtype: dict[str, BuildPluginResult]
+        :raises Exception: If a given plugin identifier is not found in any
+                           loaded plugin set.
+        """
+        plugin_ids: list[PluginIdentifier] = plugin_id_or_plugin_ids if isinstance(plugin_id_or_plugin_ids, list) else [plugin_id_or_plugin_ids]
         return {plugin_id: self._build_one_plugin(plugin_id) for plugin_id in plugin_ids}
 
-    def deploy_plugin(self, src_paths: list[Path], layer_ids: list[PluginRegistryLayerIdentifier], interactive: bool=False) -> dict[tuple[Path, str], list[tuple[str, str, Optional[Path], Optional[Plugin]]]]:
-        plugin_ids = [Plugin.id_from_jar(src_path) for src_path in src_paths]
+    def deploy_plugin(self,
+                      src_path_or_src_paths: Union[Path, list[Path]],
+                      layer_id_or_layer_ids: Union[PluginRegistryLayerIdentifier, list[PluginRegistryLayerIdentifier]],
+                      interactive: bool=False) -> dict[tuple[Path, PluginIdentifier], list[DeployPluginResult]]:
+        """
+        Deploys zero or more plugins.
+
+        :param src_path_or_src_paths: Either one signed JAR file paths or a list
+                                      of signed JAR file paths.
+        :type src_path_or_src_paths: Union[Path, list[Path]]
+        :param layer_id_or_layer_ids: Either one plugin registry layer
+                                      identifier or a list of plugin registry
+                                      layer identifiers.
+        :type layer_id_or_layer_ids: Union[PluginRegistryLayerIdentifier, list[PluginRegistryLayerIdentifier]]
+        :param interactive: Whether interactive prompts are allowed (default
+                            False).
+        :type interactive: bool
+        :return: A mapping from tuples of signed JAR file path and corresponding
+                 plugin identifier to a list of build deployment results (one
+                 per plugin registry layer); if no signed JAR file paths were
+                 given, the result is an empty mapping.
+        :rtype: dict[tuple[Path, PluginIdentifier], list[DeployPluginResult]]
+        :raises Exception: If a given plugin is not declared in any loaded
+                           plugin registry.
+        """
+        src_paths: list[Path] = src_path_or_src_paths if isinstance(src_path_or_src_paths, list) else [src_path_or_src_paths]
+        layer_ids: list[PluginRegistryLayerIdentifier] = layer_id_or_layer_ids if isinstance(layer_id_or_layer_ids, list) else [layer_id_or_layer_ids]
+        plugin_ids = [Plugin.id_from_jar(src_path) for src_path in src_paths] # FIXME: should go down to _deploy_one_plugin?
         return {(src_path, plugin_id): self._deploy_one_plugin(src_path,
                                                                plugin_id,
                                                                layer_ids,
                                                                interactive=interactive) for src_path, plugin_id in zip(src_paths, plugin_ids)}
 
-    def load_plugin_registries(self, plugin_registry_path_or_str: PathOrStr) -> TurtlesApp:
+    def load_plugin_registries(self,
+                               plugin_registry_path_or_str: PathOrStr) -> Turtles:
+        """
+        Processes the given YAML file, loading all plugin registry definitions
+        it contains, ignoring other YAML objects.
+
+        :param plugin_registry_path_or_str: A file path (or string).
+        :type plugin_registry_path_or_str: PathOrStr
+        :return: This Turtles object (for chaining).
+        :rtype: Turtles
+        :raises ExceptionGroup: If one or more errors occur while loading plugin
+                                registry definitions.
+        :raises ValueError: If the given file has already been processed or if
+                            it contains no plugin registry definitions.
+        """
         plugin_registry_path = path(plugin_registry_path_or_str)
         if plugin_registry_path in map(lambda pr: pr.get_root(), self._plugin_registries):
             raise ValueError(f'Plugin registries already loaded from: {plugin_registry_path!s}')
@@ -121,7 +197,23 @@ class TurtlesApp(object):
             raise ValueError(f'No plugin registries found in: {plugin_registry_path!s}')
         return self
 
-    def load_plugin_registry_catalogs(self, plugin_registry_catalog_path_or_str: PathOrStr) -> TurtlesApp:
+    def load_plugin_registry_catalogs(self,
+                                      plugin_registry_catalog_path_or_str: PathOrStr) -> Turtles:
+        """
+        Processes the given YAML file, loading all plugin registry catalog
+        definitions it contains and in turn all plugin registry definitions they
+        reference, ignoring other YAML objects.
+
+        :param plugin_registry_catalog_path_or_str: A file path (or string).
+        :type plugin_registry_catalog_path_or_str: PathOrStr
+        :return: This Turtles object (for chaining).
+        :rtype: Turtles
+        :raises ExceptionGroup: If one or more errors occur while loading plugin
+                                registry catalog definitions or the plugin
+                                registry definitions they reference.
+        :raises ValueError: If the given file has already been processed or if
+                            it contains no plugin registry catalog definitions.
+        """
         plugin_registry_catalog_path = path(plugin_registry_catalog_path_or_str)
         if plugin_registry_catalog_path in map(lambda prc: prc.get_root(), self._plugin_registry_catalogs):
             raise ValueError(f'Plugin registry catalogs already loaded from: {plugin_registry_catalog_path!s}')
@@ -148,7 +240,23 @@ class TurtlesApp(object):
             raise ValueError(f'No plugin registry catalogs found in: {plugin_registry_catalog_path!s}')
         return self
 
-    def load_plugin_set_catalogs(self, plugin_set_catalog_path_or_str: PathOrStr) -> TurtlesApp:
+    def load_plugin_set_catalogs(self,
+                                 plugin_set_catalog_path_or_str: PathOrStr) -> Turtles:
+        """
+        Processes the given YAML file, loading all plugin set catalog
+        definitions it contains and in turn all plugin set definitions they
+        reference, ignoring other YAML objects.
+
+        :param plugin_set_catalog_path_or_str: A file path (or string).
+        :type plugin_set_catalog_path_or_str: PathOrStr
+        :return: This Turtles object (for chaining).
+        :rtype: Turtles
+        :raises ExceptionGroup: If one or more errors occur while loading plugin
+                                set catalog definitions or the plugin set
+                                definitions they reference.
+        :raises ValueError: If the given file has already been processed or if
+                            it contains no plugin set catalog definitions.
+        """
         plugin_set_catalog_path = path(plugin_set_catalog_path_or_str)
         if plugin_set_catalog_path in map(lambda psc: psc.get_root(), self._plugin_set_catalogs):
             raise ValueError(f'Plugin set catalogs already loaded from: {plugin_set_catalog_path!s}')
@@ -175,7 +283,21 @@ class TurtlesApp(object):
             raise ValueError(f'No plugin set catalogs found in: {plugin_set_catalog_path!s}')
         return self
 
-    def load_plugin_sets(self, plugin_set_path_or_str: PathOrStr) -> TurtlesApp:
+    def load_plugin_sets(self,
+                         plugin_set_path_or_str: PathOrStr) -> Turtles:
+        """
+        Processes the given YAML file, loading all plugin set definitions it
+        contains, ignoring other YAML objects.
+
+        :param plugin_set_path_or_str: A file path (or string).
+        :type plugin_set_path_or_str: PathOrStr
+        :return: This Turtles object (for chaining).
+        :rtype: Turtles
+        :raises ExceptionGroup: If one or more errors occur while loading plugin
+                                set definitions.
+        :raises ValueError: If the given file has already been processed or if
+                            it contains no plugin set definitions.
+        """
         plugin_set_path = path(plugin_set_path_or_str)
         if plugin_set_path in map(lambda ps: ps.get_root(), self._plugin_sets):
             raise ValueError(f'Plugin sets already loaded from: {plugin_set_path!s}')
@@ -195,7 +317,23 @@ class TurtlesApp(object):
             raise ValueError(f'No plugin sets found in: {plugin_set_path!s}')
         return self
 
-    def load_plugin_signing_credentials(self, plugin_signing_credentials_path_or_str: PathOrStr) -> TurtlesApp:
+    def load_plugin_signing_credentials(self,
+                                        plugin_signing_credentials_path_or_str: PathOrStr) -> Turtles:
+        """
+        Processes the given YAML file, loading all plugin set definitions it
+        contains in search of exactly one, ignoring YAML objects of other kinds.
+
+        :param plugin_signing_credentials_path_or_str: A file path (or string).
+        :type plugin_signing_credentials_path_or_str: PathOrStr
+        :return: This Turtles object (for chaining).
+        :rtype: Turtles
+        :raises ExceptionGroup: If one or more errors occur while loading plugin
+                                signing credentials definitions.
+        :raises ValueError: If the given file has already been processed, if it
+                            contains no plugin signing credentials definitions,
+                            or if it contains more than one plugin signing
+                            credentials definitions.
+        """
         plugin_signing_credentials_path = path(plugin_signing_credentials_path_or_str)
         if self._plugin_signing_credentials:
             raise ValueError(f'Plugin signing credentials already loaded from: {self._plugin_signing_credentials.get_root()!s}')
@@ -216,7 +354,31 @@ class TurtlesApp(object):
             raise ValueError(f'Multiple plugin signing credentials found in: {plugin_signing_credentials_path!s}')
         return self
 
-    def release_plugin(self, plugin_ids: list[PluginIdentifier], layer_ids: list[PluginRegistryLayerIdentifier], interactive: bool=False) -> dict[str, list[tuple[str, str, Path, Plugin]]]:
+    def release_plugin(self,
+                       plugin_id_or_plugin_ids: Union[PluginIdentifier, list[PluginIdentifier]],
+                       layer_id_or_layer_ids: Union[PluginRegistryLayerIdentifier, list[PluginRegistryLayerIdentifier]],
+                       interactive: bool=False) -> dict[PluginIdentifier, list[DeployPluginResult]]:
+        """
+        Releases (builds then deploys) zero or more plugins.
+
+        :param plugin_id_or_plugin_ids: Either one plugin identifier, or a list
+                                        of plugin identifiers.
+        :type plugin_id_or_plugin_ids: Union[PluginIdentifier, list[PluginIdentifier]]
+        :param layer_id_or_layer_ids: Either one plugin registry layer
+                                      identifier or a list of plugin registry
+                                      layer identifiers.
+        :type layer_id_or_layer_ids: Union[PluginRegistryLayerIdentifier, list[PluginRegistryLayerIdentifier]]
+        :param interactive: Whether interactive prompts are allowed (default
+                            False).
+        :type interactive: bool
+        :return: A mapping from plugin identifier to plugin deployment result;
+                 if no plugins were given, the result is an empty mapping.
+        :rtype: dict[PluginIdentifier, list[DeployPluginResult]]
+        :raises Exception: If a given plugin is not found in any plugin set or
+                           is not declared in any loaded plugin registry.
+        """
+        plugin_ids: list[PluginIdentifier] = plugin_id_or_plugin_ids if isinstance(plugin_id_or_plugin_ids, list) else [plugin_id_or_plugin_ids]
+        layer_ids: list[PluginRegistryLayerIdentifier] = layer_id_or_layer_ids if isinstance(layer_id_or_layer_ids, list) else [layer_id_or_layer_ids]
         # ... plugin_id -> (set_id, jar_path, plugin)
         ret1 = self.build_plugin(plugin_ids)
         jar_paths = [jar_path for set_id, jar_path, plugin in ret1.values()]
@@ -226,10 +388,30 @@ class TurtlesApp(object):
                                   interactive=interactive)
         return {plugin_id: val for (jar_path, plugin_id), val in ret2.items()}
 
-    def set_password(self, pw: Union[Callable[[], str], str]) -> None:
-        self._password = pw if callable(pw) else lambda: pw
-
-    def _build_one_plugin(self, plugin_id: str) -> tuple[str, Optional[Path], Optional[Plugin]]:
+    def set_plugin_signing_password(self,
+                                    callable_or_password: Union[str, Callable[[], str]]) -> None:
+        """
+        Sets the plugin signing password callable.
+
+        :param callable_or_password: A callable returning a string (or simply a
+                                     string).
+        :type callable_or_password: Union[str, Callable[[], str]]
+        """
+        self._plugin_signing_password_callable = callable_or_password if callable(callable_or_password) else lambda: callable_or_password
+
+    def _build_one_plugin(self,
+                          plugin_id: PluginIdentifier) -> BuildPluginResult:
+        """
+        Builds one plugin.
+
+        :param plugin_id: A plugin identifier.
+        :type plugin_id: PluginIdentifier
+        :return: A plugin build result object; if the plugin set returned None,
+                 the second and third items (index 1 and 2) are None.
+        :rtype: BuildPluginResult
+        :raises Exception: If the given plugin identifier is not found in any
+                           loaded plugin set.
+        """
         for plugin_set in self._plugin_sets:
             if plugin_set.has_plugin(plugin_id):
                 bp = plugin_set.build_plugin(plugin_id,
@@ -237,15 +419,38 @@ class TurtlesApp(object):
                                              self._get_plugin_signing_alias(),
                                              self._get_plugin_signing_password())
                 return plugin_set.get_id(), bp[0] if bp else None, bp[1] if bp else None
-        raise Exception(f'{plugin_id}: not found in any plugin set')
-
-    def _deploy_one_plugin(self, src_jar: Path, plugin_id: PluginIdentifier, layer_ids: list[PluginRegistryLayerIdentifier], interactive: bool=False) -> list[tuple[str, str, Optional[Path], Optional[Plugin]]]:
+        raise Exception(f'plugin identifier not found in any loaded plugin set: {plugin_id}')
+
+    def _deploy_one_plugin(self,
+                           src_jar: Path,
+                           plugin_id: PluginIdentifier,
+                           layer_ids: list[PluginRegistryLayerIdentifier],
+                           interactive: bool=False) -> list[DeployPluginResult]:
+        """
+        Deploys a single plugin to the provided plugin registry layers of all
+        loaded plugin registries that declare the given plugin.
+
+        :param src_jar: File path of the signed JAR.
+        :type src_jar: Path
+        :param plugin_id: The corresponding plugin identifier.
+        :type plugin_id: PluginIdentifier
+        :param layer_ids: A list of plugin layer identifiers.
+        :type layer_ids: list[PluginRegistryLayerIdentifier]
+        :param interactive: Whether interactive prompts are allowed (default
+                            False).
+        :type interactive: bool
+        :return: A non-empty list of plugin deployment results; if for any, the
+                 plugin registry returned None, the third and fourth items
+                 (index 2 and 3) are None.
+        :rtype: list[DeployPluginResult]
+        :raises Exception: If the given plugin identifier is not declared in any
+                           loaded plugin registry.
+        """
         ret = list()
         for plugin_registry in self._plugin_registries:
             if plugin_registry.has_plugin(plugin_id):
                 for layer_id in layer_ids:
-                    layer = plugin_registry.get_layer(layer_id)
-                    if layer is not None:
+                    if layer := plugin_registry.get_layer(layer_id):
                         dp = layer.deploy_plugin(plugin_id,
                                                  src_jar,
                                                  interactive=interactive)
@@ -257,48 +462,136 @@ class TurtlesApp(object):
             raise Exception(f'{src_jar}: {plugin_id} not declared in any plugin registry')
         return ret
 
-    def _get_password(self) -> Optional[str]:
-        return self._password() if self._password else None
-
     def _get_plugin_signing_alias(self) -> str:
+        """
+        Returns the plugin signing alias from the loaded plugin signing
+        credentials.
+
+        :return: The plugin signing alias.
+        :rtype: str
+        """
         return self._plugin_signing_credentials.get_plugin_signing_alias()
 
     def _get_plugin_signing_keystore(self) -> Path:
+        """
+        Returns the plugin signing keystore file path from the loaded plugin
+        signing credentials.
+
+        :return: The plugin signing keystore file path.
+        :rtype: Path
+        """
         return self._plugin_signing_credentials.get_plugin_signing_keystore()
 
-    def _get_plugin_signing_password(self) -> str:
-        return self._get_password()
+    def _get_plugin_signing_password(self) -> Optional[Callable[[], str]]:
+        """
+        Returns the plugin signing password.
+
+        :return: The plugin signing password callable.
+        :rtype: Optional[Callable[[], str]]
+        """
+        return self._plugin_signing_password_callable
 
     @staticmethod
     def default_plugin_registry_catalog_choices() -> tuple[Path, ...]:
-        return TurtlesApp._default_files(TurtlesApp.PLUGIN_REGISTRY_CATALOG)
+        """
+        Returns the tuple of default plugin registry catalog file choices.
+
+        See ``CONFIG_DIRS`` and ``PLUGIN_REGISTRY_CATALOG``.
+
+        :return: A tuple of default plugin registry catalog file choices.
+        :rtype: tuple[Path, ...]
+        """
+        return Turtles._default_files(Turtles.PLUGIN_REGISTRY_CATALOG)
 
     @staticmethod
     def default_plugin_set_catalog_choices() -> tuple[Path, ...]:
-        return TurtlesApp._default_files(TurtlesApp.PLUGIN_SET_CATALOG)
+        """
+        Returns the tuple of default plugin set catalog file choices.
+
+        See ``CONFIG_DIRS`` and ``PLUGIN_SET_CATALOG``.
+
+        :return: A tuple of default plugin set catalog file choices.
+        :rtype: tuple[Path, ...]
+        """
+        return Turtles._default_files(Turtles.PLUGIN_SET_CATALOG)
 
     @staticmethod
     def default_plugin_signing_credentials_choices() -> tuple[Path, ...]:
-        return TurtlesApp._default_files(TurtlesApp.PLUGIN_SIGNING_CREDENTIALS)
+        """
+        Returns the tuple of default plugin signing credentials file choices.
+
+        See ``CONFIG_DIRS`` and ``PLUGIN_SIGNING_CREDENTIALS``.
+
+        :return: A tuple of default plugin signing credentials file choices.
+        :rtype: tuple[Path, ...]
+        """
+        return Turtles._default_files(Turtles.PLUGIN_SIGNING_CREDENTIALS)
 
     @staticmethod
     def select_default_plugin_registry_catalog() -> Optional[Path]:
-        return TurtlesApp._select_file(TurtlesApp.default_plugin_registry_catalog_choices())
+        """
+        Of the default plugin registry catalog file choices, select the first
+        one that exists.
+
+        See ``default_plugin_registry_catalog_choices`` and ``_select_file``.
+
+        :return: The first of the default plugin registry catalog file choices
+                 that exists, or None if none do.
+        :rtype: Optional[Path]
+        """
+        return Turtles._select_file(Turtles.default_plugin_registry_catalog_choices())
 
     @staticmethod
     def select_default_plugin_set_catalog() -> Optional[Path]:
-        return TurtlesApp._select_file(TurtlesApp.default_plugin_set_catalog_choices())
+        """
+        Of the default plugin set catalog file choices, select the first one
+        that exists.
+
+        See ``default_plugin_registry_set_choices`` and ``_select_file``.
+
+        :return: The first of the default plugin set catalog file choices that
+                 exists, or None if none do.
+        :rtype: Optional[Path]
+        """
+        return Turtles._select_file(Turtles.default_plugin_set_catalog_choices())
 
     @staticmethod
     def select_default_plugin_signing_credentials() -> Optional[Path]:
-        return TurtlesApp._select_file(TurtlesApp.default_plugin_signing_credentials_choices())
+        """
+        Of the default plugin signing credentials file choices, select the first
+        one that exists.
+
+        See ``default_plugin_registry_set_choices`` and ``_select_file``.
+
+        :return: The first of the default plugin signing credentials file
+                 choices that exists, or None if none do.
+        :rtype: Optional[Path]
+        """
+        return Turtles._select_file(Turtles.default_plugin_signing_credentials_choices())
 
     @staticmethod
     def _default_files(file_str) -> tuple[Path, ...]:
-        return tuple(dir_path.joinpath(file_str) for dir_path in TurtlesApp.CONFIG_DIRS)
+        """
+        Given a file base name, returns a tuple of this file in the various
+        Turtles configuration directories (``CONFIG_DIRS``).
+
+        :param file_str: A file base name.
+        :type file_str: str
+        :return: The file in the various Turtles configuration directories.
+        :rtype: tuple[Path, ...]
+        """
+        return tuple(dir_path.joinpath(file_str) for dir_path in Turtles.CONFIG_DIRS)
 
     @staticmethod
     def _select_file(choices: Iterable[Path]) -> Optional[Path]:
+        """
+        Of the given files, returns the first one that exists.
+
+        :param choices: An iterable of file paths.
+        :type choices: Iterable[Path]
+        :return: The first choice that exists, or None if none do.
+        :rtype: Optional[Path]
+        """
         for p in choices:
             if p.is_file():
                 return p