6. Turtles API Reference

6.1. `lockss.turtles`

Library and command line tool to manage LOCKSS plugin sets and LOCKSS plugin registries.

lockss.turtles.__copyright__ = 'Copyright (c) 2000-2026, Board of Trustees of Leland Stanford Jr. University': This package's copyright.

lockss.turtles.__license__ = 'Copyright (c) 2000-2026, Board of Trustees of Leland Stanford Jr. University\n\nRedistribution and use in source and binary forms, with or without\nmodification, are permitted provided that the following conditions are met:\n\n1. Redistributions of source code must retain the above copyright notice,\nthis list of conditions and the following disclaimer.\n\n2. Redistributions in binary form must reproduce the above copyright notice,\nthis list of conditions and the following disclaimer in the documentation\nand/or other materials provided with the distribution.\n\n3. Neither the name of the copyright holder nor the names of its contributors\nmay be used to endorse or promote products derived from this software without\nspecific prior written permission.\n\nTHIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"\nAND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE\nIMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE\nARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE\nLIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR\nCONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF\nSUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS\nINTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN\nCONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)\nARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE\nPOSSIBILITY OF SUCH DAMAGE.': This package's license.

lockss.turtles.__version__ = '0.7.0': This package's version.

6.2. `lockss.turtles.app`

Module to represent Turtles operations.

lockss.turtles.app.BuildPluginResult

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

alias of tuple[str, Path | None, Plugin | None]

lockss.turtles.app.DeployPluginResult

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

alias of tuple[str, str, Path | None, Plugin | None]

class lockss.turtles.app.Turtles

A Turtles command object, which can be used to execute Turtles operations.

CONFIG_DIRS: ClassVar[tuple[Path, ...]] = (PosixPath('/home/docs/.config/lockss-turtles'), PosixPath('/etc/lockss-turtles'), PosixPath('/usr/local/share/lockss-turtles')): The Turtles configuration directories in order of preference: XDG_CONFIG_DIR, ETC_CONFIG_DIR, USR_CONFIG_DIR

CONFIG_DIR_NAME: ClassVar[str] = 'lockss-turtles': The name of a Turtles configuration directory.

ETC_CONFIG_DIR: ClassVar[Path] = PosixPath('/etc/lockss-turtles'): The Turtles configuration directory under /etc.

PLUGIN_REGISTRY_CATALOG: ClassVar[str] = 'plugin-registry-catalog.yaml': The default plugin registry catalog file name.

PLUGIN_SET_CATALOG: ClassVar[str] = 'plugin-set-catalog.yaml': The default plugin set catalog file name.

PLUGIN_SIGNING_CREDENTIALS: ClassVar[str] = 'plugin-signing-credentials.yaml': The default plugin signing credentials file name.

USR_CONFIG_DIR: ClassVar[Path] = PosixPath('/usr/local/share/lockss-turtles'): The Turtles configuration directory under /usr/local/share.

XDG_CONFIG_DIR: ClassVar[Path] = PosixPath('/home/docs/.config/lockss-turtles'): The Turtles configuration directory under $XDG_CONFIG_HOME (by default $HOME/.config, which is typically /home/$USER/.config).

build_plugin(plugin_id_or_plugin_ids)

Builds zero or more plugins.

Parameters:: plugin_id_or_plugin_ids (Union[PluginIdentifier, list[PluginIdentifier]]) -- Either one plugin identifier, or a list of plugin identifiers.
Returns:: A mapping from plugin identifier to build plugin result; if no plugin identifiers were given, the result is an empty mapping.
Return type:: dict[str, BuildPluginResult]
Raises:: Exception -- If a given plugin identifier is not found in any loaded plugin set.

static default_plugin_registry_catalog_choices()

Returns the tuple of default plugin registry catalog file choices.

See CONFIG_DIRS and PLUGIN_REGISTRY_CATALOG.

Returns:: A tuple of default plugin registry catalog file choices.
Return type:: tuple[Path, ...]

static default_plugin_set_catalog_choices()

Returns the tuple of default plugin set catalog file choices.

See CONFIG_DIRS and PLUGIN_SET_CATALOG.

Returns:: A tuple of default plugin set catalog file choices.
Return type:: tuple[Path, ...]

static default_plugin_signing_credentials_choices()

Returns the tuple of default plugin signing credentials file choices.

See CONFIG_DIRS and PLUGIN_SIGNING_CREDENTIALS.

Returns:: A tuple of default plugin signing credentials file choices.
Return type:: tuple[Path, ...]

deploy_plugin(src_path_or_src_paths, layer_id_or_layer_ids, interactive=False)

Deploys zero or more plugins.

Parameters:

src_path_or_src_paths (Union[Path, list[Path]]) -- Either one signed JAR file paths or a list of signed JAR file paths.
layer_id_or_layer_ids (Union[PluginRegistryLayerIdentifier, list[PluginRegistryLayerIdentifier]]) -- Either one plugin registry layer identifier or a list of plugin registry layer identifiers.
interactive (bool) -- Whether interactive prompts are allowed (default False).

Returns:

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.

Return type:

dict[tuple[Path, PluginIdentifier], list[DeployPluginResult]]

Raises:

Exception -- If a given plugin is not declared in any loaded plugin registry.

load_plugin_registries(plugin_registry_path_or_str)

Processes the given YAML file, loading all plugin registry definitions it contains, ignoring other YAML objects.

Parameters:

plugin_registry_path_or_str (PathOrStr) -- A file path (or string).

Returns:

This Turtles object (for chaining).

Return type:

Turtles

Raises:

ExceptionGroup -- If one or more errors occur while loading plugin registry definitions.
ValueError -- If the given file has already been processed or if it contains no plugin registry definitions.

load_plugin_registry_catalogs(plugin_registry_catalog_path_or_str)

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.

Parameters:

plugin_registry_catalog_path_or_str (PathOrStr) -- A file path (or string).

Returns:

This Turtles object (for chaining).

Return type:

Turtles

Raises:

ExceptionGroup -- If one or more errors occur while loading plugin registry catalog definitions or the plugin registry definitions they reference.
ValueError -- If the given file has already been processed or if it contains no plugin registry catalog definitions.

load_plugin_set_catalogs(plugin_set_catalog_path_or_str)

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.

Parameters:

plugin_set_catalog_path_or_str (PathOrStr) -- A file path (or string).

Returns:

This Turtles object (for chaining).

Return type:

Turtles

Raises:

ExceptionGroup -- If one or more errors occur while loading plugin set catalog definitions or the plugin set definitions they reference.
ValueError -- If the given file has already been processed or if it contains no plugin set catalog definitions.

load_plugin_sets(plugin_set_path_or_str)

Processes the given YAML file, loading all plugin set definitions it contains, ignoring other YAML objects.

Parameters:

plugin_set_path_or_str (PathOrStr) -- A file path (or string).

Returns:

This Turtles object (for chaining).

Return type:

Turtles

Raises:

ExceptionGroup -- If one or more errors occur while loading plugin set definitions.
ValueError -- If the given file has already been processed or if it contains no plugin set definitions.

load_plugin_signing_credentials(plugin_signing_credentials_path_or_str)

Processes the given YAML file, loading all plugin set definitions it contains in search of exactly one, ignoring YAML objects of other kinds.

Parameters:

plugin_signing_credentials_path_or_str (PathOrStr) -- A file path (or string).

Returns:

This Turtles object (for chaining).

Return type:

Turtles

Raises:

ExceptionGroup -- If one or more errors occur while loading plugin signing credentials definitions.
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.

release_plugin(plugin_id_or_plugin_ids, layer_id_or_layer_ids, interactive=False)

Releases (builds then deploys) zero or more plugins.

Parameters:

plugin_id_or_plugin_ids (Union[PluginIdentifier, list[PluginIdentifier]]) -- Either one plugin identifier, or a list of plugin identifiers.
layer_id_or_layer_ids (Union[PluginRegistryLayerIdentifier, list[PluginRegistryLayerIdentifier]]) -- Either one plugin registry layer identifier or a list of plugin registry layer identifiers.
interactive (bool) -- Whether interactive prompts are allowed (default False).

Returns:

A mapping from plugin identifier to plugin deployment result; if no plugins were given, the result is an empty mapping.

Return type:

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.

static select_default_plugin_registry_catalog()

Of the default plugin registry catalog file choices, select the first one that exists.

See default_plugin_registry_catalog_choices and _select_file.

Returns:: The first of the default plugin registry catalog file choices that exists, or None if none do.
Return type:: Optional[Path]

static select_default_plugin_set_catalog()

Of the default plugin set catalog file choices, select the first one that exists.

See default_plugin_registry_set_choices and _select_file.

Returns:: The first of the default plugin set catalog file choices that exists, or None if none do.
Return type:: Optional[Path]

static select_default_plugin_signing_credentials()

Of the default plugin signing credentials file choices, select the first one that exists.

See default_plugin_registry_set_choices and _select_file.

Returns:: The first of the default plugin signing credentials file choices that exists, or None if none do.
Return type:: Optional[Path]

set_plugin_signing_password(callable_or_password)

Sets the plugin signing password callable.

Parameters:: callable_or_password (Union[str, Callable[[], str]]) -- A callable returning a string (or simply a string).
Return type:: None

6.3. `lockss.turtles.cli`

Command line tool for managing LOCKSS plugin sets and LOCKSS plugin registries.

class lockss.turtles.cli._Opts(*, plugin_identifier=(), plugin_identifiers=(), plugin_jar=(), plugin_jars=(), plugin_registry=(), plugin_registry_catalog=(), plugin_registry_layer=(), plugin_registry_layers=(), plugin_set=(), plugin_set_catalog=(), plugin_signing_credentials=None, plugin_signing_password=None, production=None, testing=None, headings=None, interactive=None, table_format=None)

Data class to hold parsed command line options.

Parameters:

plugin_identifier (tuple[str, ...])
plugin_identifiers (tuple[Path, ...])
plugin_jar (tuple[Path, ...])
plugin_jars (tuple[Path, ...])
plugin_registry (tuple[Path, ...])
plugin_registry_catalog (tuple[Path, ...])
plugin_registry_layer (tuple[str, ...])
plugin_registry_layers (tuple[Path, ...])
plugin_set (tuple[Path, ...])
plugin_set_catalog (tuple[Path, ...])
plugin_signing_credentials (Path | None)
plugin_signing_password (str | None)
production (bool | None)
testing (bool | None)
headings (bool | None)
interactive (bool | None)
table_format (TableFormat | None)

headings: bool | None = None

interactive: bool | None = None

plugin_identifier: tuple[str, ...] = ()

plugin_identifiers: tuple[Path, ...] = ()

plugin_jar: tuple[Path, ...] = ()

plugin_jars: tuple[Path, ...] = ()

plugin_registry: tuple[Path, ...] = ()

plugin_registry_catalog: tuple[Path, ...] = ()

plugin_registry_layer: tuple[str, ...] = ()

plugin_registry_layers: tuple[Path, ...] = ()

plugin_set: tuple[Path, ...] = ()

plugin_set_catalog: tuple[Path, ...] = ()

plugin_signing_credentials: Path | None = None

plugin_signing_password: str | None = None

production: bool | None = None

table_format: TableFormat | None = None

testing: bool | None = None

class lockss.turtles.cli._TurtlesCli(ctx)

Turtles command line application.

Parameters:: ctx (ExtraContext)

_app: Turtles

_ctx: ExtraContext

_errs: list[Exception]

_fail_if_errs()

Return type:: None

_get_plugin_identifiers()

Returns the cumulative list of plugin identifiers, from plugin_identifier and the identifiers in plugin_identifiers

files. Exits if the list of plugin identifiers ends up empty.

Returns:: The cumulative list of plugin identifiers.
Return type:: list[PluginIdentifier]

_get_plugin_jars()

Returns the cumulative list of plugin JARs, from plugin_jar and the plugin JARs in plugin_jars files. Exits if the list of plugin JARs ends up empty.

Returns:: The cumulative list of plugin JARs.
Return type:: list[Path]

_get_plugin_registries()

Returns the cumulative plugin registry files.

Returns:: The cumulative plugin registry files (possibly an empty list).
Return type:: list[Path]

_get_plugin_registry_catalogs()

Returns the cumulative plugin registry catalog files if any plugin set files or plugin registry catalog files are specified (possibly an empty list), or the first default plugin registry catalog file if no plugin registry files nor plugin registry catalog files are specified. Exits if the result is that no plugin registry catalog is available.

Returns:: The cumulative plugin registry catalog files.
Return type:: list[Path]

_get_plugin_registry_layers()

Returns the cumulative list of plugin registry layer identifiers, from plugin_registry_layer and the identifiers in plugin_registry_layers files. Exits if the list of plugin registry layers ends up empty.

Returns:: The cumulative list of plugin registry layer identifiers.
Return type:: list[PluginRegistryLayerIdentifier]

_get_plugin_set_catalogs()

Returns the cumulative plugin set catalog files if any plugin set files or plugin set catalog files are specified (possibly an empty list), or the first default plugin set catalog file if no plugin set files nor plugin set catalog files are specified. Exits if the result is that no plugin set catalog is available.

Returns:: The cumulative plugin set catalog files.
Return type:: list[Path]

_get_plugin_sets()

Returns the cumulative plugin set files.

Returns:: The cumulative plugin set files (possibly an empty list).
Return type:: list[Path]

_get_plugin_signing_credentials()

Returns the plugin signing credentials file, or the first default plugin signing credentials file if not specified. Exits if the result is that no plugin signing credentials file is available.

Returns:: The plugin signing credentials file.
Return type:: Path

_initialize_plugin_building_operation()

Initializes a plugin building operation by loading plugin set catalogs, then plugin sets, then plugin signing credentials, then obtaining the plugin signing password if necessary.

Return type:: None

_initialize_plugin_deployment_operation()

Initializes a plugin deployment operation by loading plugin registry catalogs, then plugin registries.

Return type:: None

_obtain_plugin_signing_password()

Obtains the plugin signing password if necessary.

Return type:: None

_opts: _Opts | None

build_plugin()

Implementation of the build-plugin command.

Return type:: None

deploy_plugin()

Implementation of the deploy_plugin command.

Return type:: None

dispatch(method, **cli_kwargs)

Initializes from the given command line options and invokes the given (bound) method.

Parameters:

method (Callable[[], None]) -- A (bound) method.
cli_kwargs (dict[str, Any]) -- The command line arguments passed by Click Extra.

Returns:

Return type:

None

release_plugin()

Implementation of the release-plugin command.

Return type:: None

lockss.turtles.cli._interactive_option(f): The --interactive/--non-interactive option.

lockss.turtles.cli._output_option_group(f)

The output option group: --heading/--no-headings, --table-format/-T

Parameters:: f (F)
Return type:: F

lockss.turtles.cli._plugin_building_option_group(f)

The plugin building option group: --plugin-set/-s, --plugin-set-catalog/-S, --plugin-signing-credentials/-c, --plugin-signing-password/-P

Parameters:: f (F)
Return type:: F

lockss.turtles.cli._plugin_deployment_option_group(f)

The plugin deployment option group: --plugin-registry/-r, --plugin-registry-catalog/-R

Parameters:: f (F)
Return type:: F

lockss.turtles.cli._plugin_identifier_option_group(f)

The plugin identifier option group: --plugin-identifier/-i, --plugin-identifiers/-I

Parameters:: f (F)
Return type:: F

lockss.turtles.cli._plugin_jar_option_group(f)

The plugin JAR option group: --plugin-jar/-j, --plugin-jars/-J

Parameters:: f (F)
Return type:: F

lockss.turtles.cli._plugin_registry_layer_option_group(f)

The plugin registry layer option group: --plugin-registry-layer/-l, --plugin-registry-layers/-L, --production/-p, --testing/-t

Parameters:: f (F)
Return type:: F

lockss.turtles.cli.main()

Main entry point of the module.

Return type:: None

6.4. `lockss.turtles.plugin`

Module to represent a LOCKSS plugin.

class lockss.turtles.plugin.Plugin(plugin_file, plugin_path)

An object to represent a LOCKSS plugin.

Parameters:

plugin_file (IO[AnyStr])
plugin_path (PathOrStr)

static file_to_id(plugin_fstr)

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

6.5. `lockss.turtles.plugin_registry`

Module to represent plugin registries and plugin registry catalogs.

class lockss.turtles.plugin_registry.BasePluginRegistryLayout

An abstract Pydantic model (lockss.turtles.util.BaseModelWithRoot) to represent a plugin registry layout, with concrete implementations DirectoryPluginRegistryLayout and RcsPluginRegistryLayout.

FILE_NAMING_CONVENTION_DEFAULT: ClassVar[PluginRegistryLayoutFileNamingConvention] = 'identifier': Default file naming convention.

FILE_NAMING_CONVENTION_FIELD: ClassVar[dict[str, str]] = {'alias': 'file-naming-convention', 'description': 'A file naming convention for the plugin registry layout', 'title': 'Plugin Registry Layout File Naming Convention'}: Pydantic definition of the file_naming_convention field.

TYPE_FIELD: ClassVar[dict[str, str]] = {'description': 'A plugin registry layout type', 'title': 'Plugin Registry Layout Type'}: Pydantic definition of the type field.

deploy_plugin(plugin_id, layer, src_path, interactive=False)

Deploys the given plugin to the target plugin registry layer according to this plugin registry layout's file naming convention.

See _copy_jar.

Parameters:

plugin_id (PluginIdentifier) -- A plugin identifier.
layer (PluginRegistryLayer) -- A plugin registry layer.
src_path (Path) -- The path of the plugin JAR.
interactive (bool) -- If False (the default), no interactive confirmation will occur. If True, and the given plugin is being deployed to the target layer for the very first time, the user will be prompted interactively to confirm.

Returns:

A tuple of the path of the deployed JAR and a Plugin object instantiated from the source JAR, or None if the user was prompted for confirmation and responded negatively.

Return type:

Optional[tuple[Path, Plugin]]

get_file_naming_convention()

Returns the concrete implementation's file_naming`convention field.

Returns:: This plugin registry layout's file naming convention.
Return type:: PluginRegistryLayoutFileNamingConvention

get_plugin_registry()

Returns the enclosing plugin registry.

See initialize.

Returns:: The enclosing plugin registry.
Return type:: PluginRegistry
Raises:: ValueError -- If initialize was not called on the object.

get_type()

Returns the concrete implementation's type field.

Returns:: This plugin registry layout's type.
Return type:: PluginRegistryLayoutType

initialize(plugin_registry)

Initializes the plugin registry backreference. Mandatory call after object creation.

Parameters:: plugin_registry (PluginRegistry) -- The enclosing plugin registry.
Returns:: This object (for chaining).
Return type:: BasePluginRegistryLayout

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context)

Pydantic post-initialization method, to create the _plugin_registry backreference.

See initialize.

Parameters:: context (Any) -- The Pydantic context.
Return type:: None

class lockss.turtles.plugin_registry.DirectoryPluginRegistryLayout(*, type, file_naming_convention='identifier')

A plugin registry layout that keeps plugin JARs in a single directory.

Parameters:

type (Literal['directory'])
file_naming_convention (Literal['abbreviated', 'identifier', 'underscore'])

file_naming_convention: PluginRegistryLayoutFileNamingConvention: This plugin registry layout's file naming convention.

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context)

Pydantic post-initialization method, to create the _plugin_registry backreference.

See initialize.

Parameters:: context (Any) -- The Pydantic context.
Return type:: None

type: Literal['directory']: This plugin registry layout's type.

class lockss.turtles.plugin_registry.PluginRegistry(*, kind, id, name, layout, layers, plugin_identifiers, suppressed_plugin_identifiers=[])

A Pydantic model (lockss.turtles.util.BaseModelWithRoot) to represent a plugin registry.

Parameters:

kind (Literal['PluginRegistry'])
id (str)
name (str)
layout (Annotated[DirectoryPluginRegistryLayout | RcsPluginRegistryLayout, FieldInfo(annotation=NoneType, required=True, discriminator='type')])
layers (list[PluginRegistryLayer])
plugin_identifiers (list[str])
suppressed_plugin_identifiers (list[str])

get_id()

Returns this plugin registry's identifier.

Returns:: This plugin registry's identifier.
Return type:: PluginRegistryIdentifier

get_layer(layer_id)

Returns the plugin registry layer with the given identifier.

Parameters:: layer_id (PluginRegistryLayerIdentifier) -- A plugin registry layer identifier.
Returns:: The plugin registry layer from this registry with the given identifier, or None if there is no such layer.
Return type:: Optional[PluginRegistryLayer]

get_layer_ids()

Returns a list of all the plugin registry layer identifiers in this registry.

Returns:: A list of plugin registry layer identifiers.
Return type:: list[PluginRegistryLayerIdentifier]

get_layers()

Returns a list of all the plugin registry layers in this registry.

Returns:: A list of plugin registry layers.
Return type:: list[PluginRegistryLayer]

get_layout()

Returns this plugin registry's layout.

Returns:: A list of plugin registry layers.
Return type:: list[PluginRegistryLayer]

get_name()

Returns this plugin registry's name.

Returns:: This plugin registry's name.
Return type:: str

get_plugin_identifiers()

Returns the list of plugin identifiers in this registry.

Returns:: The list of plugin identifiers in this registry.
Return type:: list[PluginIdentifier]

get_suppressed_plugin_identifiers()

Returns the list of suppressed plugin identifiers in this registry.

Returns:: The list of suppressed plugin identifiers in this registry.
Return type:: list[PluginIdentifier]

has_plugin(plugin_id)

Determines if a given plugin identifier is in this registry.

Parameters:: plugin_id (PluginIdentifier) -- A plugin identifier.
Returns:: True if and only if the given plugin identifier is in this registry.
Return type:: bool

id: PluginRegistryIdentifier: This plugin registry's identifier.

kind: PluginRegistryKind: This object's kind.

layers: list[PluginRegistryLayer]: This plugin registry's layers.

layout: PluginRegistryLayout: This plugin registry's layout.

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context)

Pydantic post-initialization method to initialize the layout and all the layers with this registry as the enclosing registry.

See BasePluginRegistrLayout.initialize and PluginRegistryLayout.initialize.

Parameters:: context (Any) -- The Pydantic context.
Return type:: None

name: str: This plugin registry's name.

plugin_identifiers: list[PluginIdentifier]: The plugin identifiers in this registry.

suppressed_plugin_identifiers: list[PluginIdentifier]: The suppressed plugin identifiers, formerly in this plugin registry.

class lockss.turtles.plugin_registry.PluginRegistryCatalog(*, kind, plugin_registry_files)

A Pydantic model (lockss.turtles.util.BaseModelWithRoot) to represent a plugin registry catalog.

Parameters:

kind (Literal['PluginRegistryCatalog'])
plugin_registry_files (list[str])

get_plugin_registry_files()

Returns the list of plugin registry files in this catalog, relative to the plugin registry catalog file if applicable.

Returns:: A non-null list of plugin registry file paths.
Return type:: list[Path]

kind: PluginRegistryCatalogKind: This object's kind.

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context)

Pydantic post-initialization method to create the _root field.

Parameters:: context (Any)
Return type:: None

plugin_registry_files: list[str]: A non-empty list of plugin registry files.

lockss.turtles.plugin_registry.PluginRegistryCatalogKind

A type alias for the plugin registry catalog kind.

alias of Literal['PluginRegistryCatalog']

lockss.turtles.plugin_registry.PluginRegistryIdentifier: A type alias for plugin registry identifiers.

lockss.turtles.plugin_registry.PluginRegistryKind

A type alias for the plugin registry kind.

alias of Literal['PluginRegistry']

class lockss.turtles.plugin_registry.PluginRegistryLayer(*, id, name, path)

A Pydantic model to represent a plugin registry layer.

Parameters:

id (str)
name (str)
path (str)

deploy_plugin(plugin_id, src_path, interactive=False)

Deploys the given plugin to this plugin registry layer according to this plugin registry layout's file naming convention.

Parameters:

plugin_id (PluginIdentifier) -- A plugin identifier.
src_path (Path) -- The path of the plugin JAR.
interactive (bool) -- If False (the default), no interactive confirmation will occur. If True, and the given plugin is being deployed to this layer for the very first time, the user will be prompted interactively to confirm.

Returns:

A tuple of the path of the deployed JAR and a Plugin object instantiated from the source JAR, or None if the user was prompted for confirmation and responded negatively.

Return type:

Optional[tuple[Path, Plugin]]

get_id()

Returns this plugin registry layer's identifier.

Returns:: This plugin registry layer's identifier.
Return type:: PluginRegistryLayerIdentifier

get_jars()

Returns the list of this plugin registry layer's JAR file paths.

Returns:: A sorted list of JAR file paths.
Return type:: list[Path]

get_name()

Returns this plugin registry layer's name.

Returns:: This plugin registry layer's name.
Return type:: str

get_path()

Returns this plugin registry layer's path.

Returns:: This plugin registry layer's path.
Return type:: Path

get_plugin_registry()

Returns the enclosing plugin registry.

See initialize.

Returns:: The enclosing plugin registry.
Return type:: PluginRegistry
Raises:: ValueError -- If initialize was not called on the object.

id: PluginRegistryLayerIdentifier: This plugin registry layer's identifier.

initialize(plugin_registry)

Initializes the plugin registry backreference. Mandatory call after object creation.

Parameters:: plugin_registry (PluginRegistry) -- The enclosing plugin registry.
Returns:: This object (for chaining).
Return type:: BasePluginRegistryLayout

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context)

Pydantic post-initialization method, to create the _plugin_registry backreference.

See initialize.

Parameters:: context (Any) -- The Pydantic context.
Return type:: None

name: str: This plugin registry layer's name.

path: str: This plugin registry layer's path.

lockss.turtles.plugin_registry.PluginRegistryLayerIdentifier: A type alias for plugin registry layer identifiers.

lockss.turtles.plugin_registry.PluginRegistryLayout

A type alias for plugin registry layouts, which is the union of DirectoryPluginRegistryLayout and RcsPluginRegistryLayout using type as the discriminator field.

alias of Annotated[DirectoryPluginRegistryLayout | RcsPluginRegistryLayout, FieldInfo(annotation=NoneType, required=True, discriminator='type')]

lockss.turtles.plugin_registry.PluginRegistryLayoutFileNamingConvention

A type alias for the three plugin registry layout file naming conventions.

alias of Literal['abbreviated', 'identifier', 'underscore']

lockss.turtles.plugin_registry.PluginRegistryLayoutType

A type alias for the two plugin registry layout types.

alias of Literal['directory', 'rcs']

class lockss.turtles.plugin_registry.RcsPluginRegistryLayout(*, type, file_naming_convention='identifier')

A plugin registry layout that is like DirectoryPluginRegistryLayout but also uses GNU RCS to keep a record of successive plugin versions in an RCS subdirectory.

Parameters:

type (Literal['rcs'])
file_naming_convention (Literal['abbreviated', 'identifier', 'underscore'])

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context)

Pydantic post-initialization method, to create the _plugin_registry backreference.

See initialize.

Parameters:: context (Any) -- The Pydantic context.
Return type:: None

type: Literal['rcs']: This plugin registry layout's type. Shadows that of DirectoryPluginRegistryLayout due to inheritance.

6.6. `lockss.turtles.plugin_set`

Module to represent plugin sets and plugin set catalogs.

class lockss.turtles.plugin_set.AntPluginSetBuilder(*, type, main='plugins/src', test='plugins/test/src')

A plugin set builder that uses Java Development Kit (JDK) 8 and Apache Ant, with the legacy LOCKSS 1.x build system.

Parameters:

type (Literal['ant'])
main (str)
test (str)

DEFAULT_MAIN: ClassVar[str] = 'plugins/src': Default value for the main field.

DEFAULT_TEST: ClassVar[str] = 'plugins/test/src': Default value for the test field.

build_plugin(plugin_id, keystore_path, keystore_alias, keystore_password=None)

Builds the given plugin with the supplied plugin signing credentials.

Parameters:

plugin_id (PluginIdentifier) -- A plugin identifier.
keystore_path (Path) -- The path to the plugin signing keystore.
keystore_alias (str) -- The alias to use in the plugin signing keystore.
keystore_password (Optional[Callable[[], str]]) -- The plugin signing password.

Returns:

A tuple of the built and signed JAR file and a Plugin object instantiated from it.

Return type:

tuple[Path, Plugin]

Raises:

Exception -- If JAVA_HOME is not set in the environment.
subprocess.CalledProcessError -- If a subprocess fails.
FileNotFoundError -- If the expected built and signed plugin JAR path is unexpectedly not found despite the build.

main: str: This plugin set builder's main code path.

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context)

Pydantic post-initialization method to initialize the _built flag.

Parameters:: context (Any) -- The Pydantic context.
Return type:: None

test: str: This plugin set builder's unit test path.

type: Literal['ant']: This plugin set builder's type.

class lockss.turtles.plugin_set.BasePluginSetBuilder

An abstract Pydantic model (lockss.turtles.util.BaseModelWithRoot) to represent a plugin set builder, with concrete implementations MavenPluginSetBuilder and AntPluginSetBuilder.

MAIN_FIELD: ClassVar[dict[str, str]] = {'description': "The path to the plugins' source code, relative to the root of the project", 'title': 'Main Code Path'}: Pydantic definition of the main field.

TEST_FIELD: ClassVar[dict[str, str]] = {'description': "The path to the plugins' unit tests, relative to the root of the project", 'title': 'Test Code Path'}: Pydantic definition of the test field.

TYPE_FIELD: ClassVar[dict[str, str]] = {'description': 'A plugin builder type', 'title': 'Plugin Builder Type'}: Pydantic definition of the type field.

abstractmethod build_plugin(plugin_id, keystore_path, keystore_alias, keystore_password=None)

Builds the given plugin, using the given plugin signing credentials.

Parameters:

plugin_id (PluginIdentifier) -- A plugin identifier.
keystore_path (Path) -- The path to the plugin signing keystore.
keystore_alias (str) -- The signing alias to use from the plugin signing keystore.
keystore_password (Any) -- The signing password.

Returns:

A tuple of the plugin JAR path and the corresponding Plugin object.

Return type:

tuple[Path, Plugin]

get_main()

Returns this plugin set builder's main code path (relative to the root if not absolute).

Returns:: This plugin set's main code path.
Return type:: Path
Raises:: ValueError -- If this object is not properly initialized.

get_test()

Returns this plugin set builder's unit test path (relative to the root if not absolute).

Returns:: This plugin set's unit test path.
Return type:: Path
Raises:: ValueError -- If this object is not properly initialized.

get_type()

Returns this plugin set builder's type.

Returns:: This plugin set builder's type.
Return type:: PluginSetBuilderType

has_plugin(plugin_id)

Determines if the given plugin identifier represents a plugin that is present in the plugin set.

Parameters:: plugin_id (PluginIdentifier) -- A plugin identifier.
Returns:: Whether the plugin is present in the plugin set.
Return type:: bool

make_plugin(plugin_id)

Makes a Plugin object from the given plugin identifier.

Parameters:: plugin_id (PluginIdentifier) -- A plugin identifier.
Returns:: The corresponding Plugin object.
Return type:: Plugin

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context)

Pydantic post-initialization method to create the _root field.

Parameters:: context (Any)
Return type:: None

class lockss.turtles.plugin_set.MavenPluginSetBuilder(*, type, main='src/main/java', test='src/test/java')

A plugin set builder that uses Java Development Kit (JDK) 17 and Apache Maven, with the parent POM org.lockss:lockss-plugins-parent-pom.

Parameters:

type (Literal['maven'])
main (str)
test (str)

DEFAULT_MAIN: ClassVar[str] = 'src/main/java': The default value for main.

DEFAULT_TEST: ClassVar[str] = 'src/test/java': The default value for test.

build_plugin(plugin_id, keystore_path, keystore_alias, keystore_password=None)

Builds the given plugin with the supplied plugin signing credentials.

Parameters:

plugin_id (PluginIdentifier) -- A plugin identifier.
keystore_path (Path) -- The path to the plugin signing keystore.
keystore_alias (str) -- The alias to use in the plugin signing keystore.
keystore_password -- The plugin signing password.

Returns:

A tuple of the built and signed JAR file and a Plugin object instantiated from it.

Return type:

tuple[Path, Plugin]

Raises:

subprocess.CalledProcessError -- If a subprocess fails.
FileNotFoundError -- If the expected built and signed plugin JAR path is unexpectedly not found despite the build.

main: str: This plugin set builder's main code path.

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context)

Pydantic post-initialization method to initialize the _built flag.

Parameters:: context (Any) -- The Pydantic context.
Return type:: None

test: str: This plugin set builder's unit test path.

type: Literal['maven']: This Plugin set builder's type.

class lockss.turtles.plugin_set.PluginSet(*, kind, id, name, builder)

A Pydantic model for a plugin set.

Parameters:

kind (Literal['PluginSet'])
id (str)
name (str)
builder (MavenPluginSetBuilder | AntPluginSetBuilder)

build_plugin(plugin_id, keystore_path, keystore_alias, keystore_password=None)

Builds the given plugin with the supplied plugin signing credentials.

Parameters:

plugin_id (PluginIdentifier) -- A plugin identifier.
keystore_path (Path) -- The path to the plugin signing keystore.
keystore_alias (str) -- The alias to use in the plugin signing keystore.
keystore_password (Optional[Callable[[], str]]) -- The plugin signing password.

Returns:

A tuple of the built and signed JAR file and a Plugin object instantiated from it.

Return type:

tuple[Path, Plugin]

builder: PluginSetBuilder: This plugin set's builder.

get_builder()

Returns this plugin set's builder.

Returns:: This plugin set's builder.
Return type:: PluginSetBuilder

get_id()

Returns this plugin set's identifier.

Returns:: This plugin set's identifier.
Return type:: PluginSetIdentifier

get_name()

Returns this plugin set's name.

Returns:: This plugin set's name.
Return type:: str

has_plugin(plugin_id)

Determines if the given plugin identifier represents a plugin that is present in the plugin set.

Parameters:: plugin_id (PluginIdentifier) -- A plugin identifier.
Returns:: Whether the plugin is present in the plugin set.
Return type:: bool

id: PluginSetIdentifier: This plugin set's identifier.

initialize(root)

Mandatory initialization of the builder.

Parameters:: root (Path) -- This plugin set's root path.
Returns:: This plugin set, for chaining.
Return type:: PluginSet

kind: PluginSetKind: This object's kind.

make_plugin(plugin_id)

Makes a Plugin object from the given plugin identifier.

Parameters:: plugin_id (PluginIdentifier) -- A plugin identifier.
Returns:: The corresponding Plugin object.
Return type:: Plugin

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

name: str: This plugin set's name.

lockss.turtles.plugin_set.PluginSetBuilder

A type alias for plugin set builders, which is the union of MavenPluginSetBuilder and AntPluginSetBuilder using type as the discriminator field.

alias of Annotated[MavenPluginSetBuilder | AntPluginSetBuilder, FieldInfo(annotation=NoneType, required=True, discriminator='type')]

lockss.turtles.plugin_set.PluginSetBuilderType

A type alias for the plugin set builder type.

alias of Literal['ant', 'maven']

class lockss.turtles.plugin_set.PluginSetCatalog(*, kind, plugin_set_files)

A Pydantic model (lockss.turtles.util.BaseModelWithRoot) to represent a plugin set catalog.

Parameters:

kind (Literal['PluginSetCatalog'])
plugin_set_files (Annotated[list[str], MinLen(min_length=1)])

get_plugin_set_files()

Return this plugin set catalog's list of plugin set definition file paths (relative to the root if not absolute).

Returns:: A list of plugin set definition file paths.
Return type:: list[Path]

kind: PluginSetCatalogKind: This object's kind.

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context)

Pydantic post-initialization method to create the _root field.

Parameters:: context (Any)
Return type:: None

plugin_set_files: list[str]: A non-empty list of plugin set files.

lockss.turtles.plugin_set.PluginSetCatalogKind

A type alias for the plugin set catalog kind.

alias of Literal['PluginSetCatalog']

lockss.turtles.plugin_set.PluginSetIdentifier: A type alias for plugin set identifiers.

lockss.turtles.plugin_set.PluginSetKind

A type alias for the plugin set kind.

alias of Literal['PluginSet']

6.7. `lockss.turtles.util`

Utility module.

class lockss.turtles.util.BaseModelWithRoot

A Pydantic model with a root path which can be used to resolve relative paths.

get_root()

Returns this object's root path.

See initialize.

Returns:: This object's root path.
Return type:: Path
Raises:: ValueError -- If this object's initialize method was not called.

initialize(root_path_or_str)

Mandatory initialization of the root path.

Parameters:: root_path_or_str (PathOrStr) -- This object's root path.
Returns:: This object, for chaining.
Return type:: BaseModelWithRoot

model_config = {}: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

model_post_init(context)

Pydantic post-initialization method to create the _root field.

Parameters:: context (Any)
Return type:: None

lockss.turtles.util.PathOrStr

Type alias for the union of Path and str.

alias of Path | str

lockss.turtles.util.file_or(paths)

Turns an iterable of file paths into a " or "-separated string suitable for CLI messages.

Parameters:: paths (Iterable[Path]) -- A non-null list of file paths.
Returns:: A " or "-separated string of the given file paths.
Return type:: str

6. Turtles API Reference

6.1. lockss.turtles

6.2. lockss.turtles.app

6.3. lockss.turtles.cli

6.4. lockss.turtles.plugin

6.5. lockss.turtles.plugin_registry

6.6. lockss.turtles.plugin_set

6.7. lockss.turtles.util

6.1. `lockss.turtles`

6.2. `lockss.turtles.app`

6.3. `lockss.turtles.cli`

6.4. `lockss.turtles.plugin`

6.5. `lockss.turtles.plugin_registry`

6.6. `lockss.turtles.plugin_set`

6.7. `lockss.turtles.util`