lockss-pybasic 0.1.0__tar.gz

lockss_pybasic-0.1.0/CHANGELOG.rst

@@ -0,0 +1,19 @@
+=============
+Release Notes
+=============
+
+-----
+0.1.0
+-----
+
+Released: 2025-07-01
+
+Initial release, including:
+
+*  ``cliutil``
+
+*  ``errorutil``
+
+*  ``fileutil``
+
+*  ``outpututil``

lockss_pybasic-0.1.0/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.

lockss_pybasic-0.1.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.3
+Name: lockss-pybasic
+Version: 0.1.0
+Summary: Basic Python utilities
+License: BSD-3-Clause
+Author: Thib Guicherd-Callin
+Author-email: thib@cs.stanford.edu
+Maintainer: Thib Guicherd-Callin
+Maintainer-email: thib@cs.stanford.edu
+Requires-Python: >=3.9,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: BSD License
+Classifier: Programming Language :: Python
+Classifier: Topic :: Software Development :: Libraries
+Requires-Dist: pydantic (>=2.11.0,<3.0.0)
+Requires-Dist: pydantic-argparse (>=0.10.0,<0.11.0)
+Requires-Dist: rich-argparse (>=1.7.0,<1.8.0)
+Requires-Dist: tabulate (>=0.9.0,<0.10.0)
+Project-URL: Repository, https://github.com/lockss/lockss-pybasic
+Description-Content-Type: text/x-rst
+
+==============
+lockss-pybasic
+==============
+
+.. |RELEASE| replace:: 0.1.0
+.. |RELEASE_DATE| replace:: 2025-07-01
+
+**Latest release:** |RELEASE| (|RELEASE_DATE|)
+
+``lockss-pybasic`` provides basic utilities for various LOCKSS projects written in Python.
+
+-------
+Modules
+-------
+
+``lockss.pybasic.cliutil``
+   Command line utilities.
+
+   *  ``BaseCli`` is a base class for command line interfaces that uses `pydantic-argparse <https://pypi.org/project/pydantic-argparse/>`_ to define arguments and subcommands, and `rich-argparse <https://pypi.org/project/rich-argparse/>`_ to display help messages. For each command ``x-y-z`` induced by a ``pydantic-argparse`` field named ``x_y_z`` deriving from ``BaseModel`` , the ``dispatch()`` method expects a method named ``_x_y_z``.
+
+   *  ``StringCommand`` provides a `pydantic-argparse <https://pypi.org/project/pydantic-argparse/>`_ way to define a subcommand whose only purpose is printing a string, with ``COPYRIGHT_DESCRIPTION``, ``LICENSE_DESCRIPTION`` and ``VERSION_DESCRIPTION`` constants provided for convenience. Example:
+
+      .. code-block:: python
+
+         class MyCliModel(BaseModel):
+             copyright: Optional[StringCommand.type(my_copyright_string)] = Field(description=COPYRIGHT_DESCRIPTION)
+
+   *  ``at_most_one_from_enum`` and ``get_from_enum`` provide a facility for defining a `pydantic-argparse <https://pypi.org/project/pydantic-argparse/>`_ model that defines one command line option per constant of an ``Enum``, using an ``enum`` keyword argument in the ``Field`` definition. Example:
+
+      .. code-block:: python
+
+         class Orientation(Enum):
+             horizontal = 1
+             vertical = 2
+             diagonal = 3
+
+         DEFAULT_ORIENTATION = Orientation.horizontal
+
+         class MyCliModel(BaseModel):
+             diagonal: Optional[bool] = Field(False, description='display diagonally', enum=Orientation)
+             horizontal: Optional[bool] = Field(False, description='display horizontally', enum=Orientation)
+             unrelated: Optional[bool] = Field(...)
+             vertical: Optional[bool] = Field(False, description='display vertically', enum=Orientation)
+
+             @root_validator
+             def _at_most_one_orientation(cls, values):
+                 return at_most_one_from_enum(cls, values, Orientation)
+
+             def get_orientation(self) -> Orientation:
+                 return get_from_enum(self, Orientation, DEFAULT_ORIENTATION)
+
+``lockss.pybasic.errorutil``
+   Error and exception utilities.
+
+   *  ``InternalError`` is a no-arg subclass of ``RuntimeError``.
+
+``lockss.pybasic.fileutil``
+   File and path utilities.
+
+   *  ``file_lines`` returns the non-empty lines of a file stripped of comments that begin with ``#`` and run to the end of a line.
+
+   *  ``path`` takes a string or ``PurePath`` and returns a ``Path`` for which ``Path.expanduser()`` and ``Path.resolve()`` have been called.
+
+``lockss.pybasic.outpututil``
+   Utilities to work with `tabulate <https://pypi.org/project/tabulate/>`_.
+
+   *  ``OutputFormat`` is an ``Enum`` of all the output formats from ``tabulate.tabulate_formats``.
+
+   *  ``OutputFormatOptions`` defines a `pydantic-argparse <https://pypi.org/project/pydantic-argparse/>`_ model for setting an output format from ``OutputFormat``.
+
+-------------
+Release Notes
+-------------
+
+See `<CHANGELOG.rst>`_.

lockss_pybasic-0.1.0/README.rst

@@ -0,0 +1,75 @@
+==============
+lockss-pybasic
+==============
+
+.. |RELEASE| replace:: 0.1.0
+.. |RELEASE_DATE| replace:: 2025-07-01
+
+**Latest release:** |RELEASE| (|RELEASE_DATE|)
+
+``lockss-pybasic`` provides basic utilities for various LOCKSS projects written in Python.
+
+-------
+Modules
+-------
+
+``lockss.pybasic.cliutil``
+   Command line utilities.
+
+   *  ``BaseCli`` is a base class for command line interfaces that uses `pydantic-argparse <https://pypi.org/project/pydantic-argparse/>`_ to define arguments and subcommands, and `rich-argparse <https://pypi.org/project/rich-argparse/>`_ to display help messages. For each command ``x-y-z`` induced by a ``pydantic-argparse`` field named ``x_y_z`` deriving from ``BaseModel`` , the ``dispatch()`` method expects a method named ``_x_y_z``.
+
+   *  ``StringCommand`` provides a `pydantic-argparse <https://pypi.org/project/pydantic-argparse/>`_ way to define a subcommand whose only purpose is printing a string, with ``COPYRIGHT_DESCRIPTION``, ``LICENSE_DESCRIPTION`` and ``VERSION_DESCRIPTION`` constants provided for convenience. Example:
+
+      .. code-block:: python
+
+         class MyCliModel(BaseModel):
+             copyright: Optional[StringCommand.type(my_copyright_string)] = Field(description=COPYRIGHT_DESCRIPTION)
+
+   *  ``at_most_one_from_enum`` and ``get_from_enum`` provide a facility for defining a `pydantic-argparse <https://pypi.org/project/pydantic-argparse/>`_ model that defines one command line option per constant of an ``Enum``, using an ``enum`` keyword argument in the ``Field`` definition. Example:
+
+      .. code-block:: python
+
+         class Orientation(Enum):
+             horizontal = 1
+             vertical = 2
+             diagonal = 3
+
+         DEFAULT_ORIENTATION = Orientation.horizontal
+
+         class MyCliModel(BaseModel):
+             diagonal: Optional[bool] = Field(False, description='display diagonally', enum=Orientation)
+             horizontal: Optional[bool] = Field(False, description='display horizontally', enum=Orientation)
+             unrelated: Optional[bool] = Field(...)
+             vertical: Optional[bool] = Field(False, description='display vertically', enum=Orientation)
+
+             @root_validator
+             def _at_most_one_orientation(cls, values):
+                 return at_most_one_from_enum(cls, values, Orientation)
+
+             def get_orientation(self) -> Orientation:
+                 return get_from_enum(self, Orientation, DEFAULT_ORIENTATION)
+
+``lockss.pybasic.errorutil``
+   Error and exception utilities.
+
+   *  ``InternalError`` is a no-arg subclass of ``RuntimeError``.
+
+``lockss.pybasic.fileutil``
+   File and path utilities.
+
+   *  ``file_lines`` returns the non-empty lines of a file stripped of comments that begin with ``#`` and run to the end of a line.
+
+   *  ``path`` takes a string or ``PurePath`` and returns a ``Path`` for which ``Path.expanduser()`` and ``Path.resolve()`` have been called.
+
+``lockss.pybasic.outpututil``
+   Utilities to work with `tabulate <https://pypi.org/project/tabulate/>`_.
+
+   *  ``OutputFormat`` is an ``Enum`` of all the output formats from ``tabulate.tabulate_formats``.
+
+   *  ``OutputFormatOptions`` defines a `pydantic-argparse <https://pypi.org/project/pydantic-argparse/>`_ model for setting an output format from ``OutputFormat``.
+
+-------------
+Release Notes
+-------------
+
+See `<CHANGELOG.rst>`_.

lockss_pybasic-0.1.0/pyproject.toml

@@ -0,0 +1,73 @@
+# Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its contributors
+# may be used to endorse or promote products derived from this software without
+# specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+[project]
+name = "lockss-pybasic"
+version = "0.1.0" # Always change in __init__.py, and at release time in README.rst and CHANGELOG.rst
+description = "Basic Python utilities"
+license = { text = "BSD-3-Clause" }
+readme = "README.rst"
+requires-python = ">=3.9,<4.0"
+authors = [
+    { name = "Thib Guicherd-Callin", email = "thib@cs.stanford.edu" },
+]
+maintainers = [
+    { name = "Thib Guicherd-Callin", email = "thib@cs.stanford.edu" },
+]
+dependencies = [
+    "pydantic (>=2.11.0,<3.0.0)",
+    "pydantic-argparse (>=0.10.0,<0.11.0)",
+    "rich-argparse (>=1.7.0,<1.8.0)",
+    "tabulate (>=0.9.0,<0.10.0)",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Framework :: Pydantic :: 2",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: BSD License",
+    "Programming Language :: Python",
+    "Topic :: Software Development :: Libraries",
+]
+
+[project.urls]
+repository = "https://github.com/lockss/lockss-pybasic"
+
+[tool.poetry]
+include = [
+    "CHANGELOG.rst",
+    "LICENSE",
+    "README.rst",
+]
+packages = [
+    { include = "lockss", from = "src" }
+]
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"

lockss_pybasic-0.1.0/src/lockss/pybasic/__init__.py

@@ -0,0 +1,39 @@
+#!/usr/bin/env python3
+
+"""
+Basic Python utilities.
+"""
+
+__copyright__ = '''
+Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+'''.strip()
+
+__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:
+
+1. Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGE.
+'''.strip()
+
+__version__ = '0.1.0'

lockss_pybasic-0.1.0/src/lockss/pybasic/cliutil.py

@@ -0,0 +1,242 @@
+#!/usr/bin/env python3
+
+# Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its contributors
+# may be used to endorse or promote products derived from this software without
+# specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+Command line utilities.
+"""
+
+from collections.abc import Callable
+import sys
+from typing import Any, Dict, Generic, Optional, TypeVar
+
+from pydantic.v1 import BaseModel
+from pydantic_argparse import ArgumentParser
+from pydantic_argparse.argparse.actions import SubParsersAction
+from rich_argparse import RichHelpFormatter
+
+
+class ActionCommand(Callable, BaseModel):
+    """
+    Base class for a pydantic-argparse style command.
+    """
+    pass
+
+
+class StringCommand(ActionCommand):
+    """
+    A pydantic-argparse style command that prints a string.
+
+    Example of use:
+
+    .. code-block:: python
+
+       class MyCliModel(BaseModel):
+           copyright: Optional[StringCommand.type(my_copyright_string)] = Field(description=COPYRIGHT_DESCRIPTION)
+
+    See also the convenience constants ``COPYRIGHT_DESCRIPTION``,
+    ``LICENSE_DESCRIPTION``, and ``VERSION_DESCRIPTION``.
+    """
+
+    @staticmethod
+    def type(display_str: str):
+        class _StringCommand(StringCommand):
+            def __call__(self, file=sys.stdout, **kwargs):
+                print(display_str, file=file)
+        return _StringCommand
+
+
+COPYRIGHT_DESCRIPTION = 'print the copyright and exit'
+LICENSE_DESCRIPTION = 'print the software license and exit'
+VERSION_DESCRIPTION = 'print the version number and exit'
+
+
+BaseModelT = TypeVar('BaseModelT', bound=BaseModel)
+
+
+class BaseCli(Generic[BaseModelT]):
+    """
+    Base class for general CLI functionality.
+
+    ``BaseModelT`` represents a Pydantic-Argparse model type deriving from
+    ``BaseModel``.
+
+    For each command ``x-y-z`` induced by a Pydantic-Argparse field named
+    ``x_y_z`` deriving from ``BaseModel`` , the ``dispatch()`` method expects a
+    method named ``_x_y_z``.
+    """
+
+    def __init__(self, **kwargs):
+        """
+        Constructs a new ``BaseCli`` instance.
+
+        :param kwargs: Keyword arguments. Must include ``model``, the
+                       ``BaseModel`` type corresponding to ``BaseModelT``. Must
+                       include ``prog``, the command-line name of the program.
+                       Must include ``description``, the description string of
+                       the program.
+        :type kwargs: Dict[str, Any]
+        """
+        super().__init__()
+        self._args: Optional[BaseModelT] = None
+        self._parser: Optional[ArgumentParser] = None
+        self.extra: Dict[str, Any] = dict(**kwargs)
+
+    def run(self) -> None:
+        """
+        Runs the command line tool:
+
+        *  Creates a Pydantic-Argparse ``ArgumentParser`` with ``model``,
+           ``prog`` and ``description`` from the constructor keyword
+           arguments in ``self.parser``.
+
+        *  Stores the Pydantic-Argparse parsed arguments in ``self.args``.
+
+        *  Calls ``dispatch()``.
+        """
+        self._parser: ArgumentParser = ArgumentParser(model=self.extra.get('model'),
+                                                      prog=self.extra.get('prog'),
+                                                      description=self.extra.get('description'))
+        self._initialize_rich_argparse()
+        self._args = self._parser.parse_typed_args()
+        self.dispatch()
+
+    def dispatch(self) -> None:
+        """
+        Dispatches from the first field ``x_y_z`` in ``self.args`` that is a
+        command (i.e. whose value derives from ``BaseModel``) to a method
+        called ``_x_y_z``.
+        """
+        field_names = self._args.__class__.__fields__.keys()
+        for field_name in field_names:
+            field_value = getattr(self._args, field_name)
+            if issubclass(type(field_value), BaseModel):
+                func = getattr(self, f'_{field_name}')
+                if callable(func):
+                    func(field_value)
+                else:
+                    self._parser.exit(1, f'internal error: no _{field_name} callable for the {field_name} command')
+                break
+        else:
+            self._parser.error(f'unknown command; expected one of {', '.join(field_names)}')
+
+    def _initialize_rich_argparse(self) -> None:
+        """
+        Initializes `rich-argparse <https://pypi.org/project/rich-argparse/>`_
+        for this instance.
+        """
+        self._initialize_rich_argparse_styles()
+        def __add_formatter_class(container):
+            container.formatter_class = RichHelpFormatter
+            if hasattr(container, '_actions'):
+                for action in container._actions:
+                    if issubclass(type(action), SubParsersAction):
+                        for subaction in action.choices.values():
+                            __add_formatter_class(subaction)
+        __add_formatter_class(self._parser)
+
+    def _initialize_rich_argparse_styles(self) -> None:
+        # See https://github.com/hamdanal/rich-argparse#customize-the-colors
+        for cls in [RichHelpFormatter]:
+            cls.styles.update({
+                'argparse.args': 'bold cyan',  # for positional-arguments and --options (e.g "--help")
+                'argparse.groups': 'underline dark_orange',  # for group names (e.g. "positional arguments")
+                'argparse.help': 'default',  # for argument's help text (e.g. "show this help message and exit")
+                'argparse.metavar': 'italic dark_cyan',  # for metavariables (e.g. "FILE" in "--file FILE")
+                'argparse.prog': 'bold grey50',  # for %(prog)s in the usage (e.g. "foo" in "Usage: foo [options]")
+                'argparse.syntax': 'bold',  # for highlights of back-tick quoted text (e.g. "`some text`")
+                'argparse.text': 'default',  # for descriptions, epilog, and --version (e.g. "A program to foo")
+                'argparse.default': 'italic',  # for %(default)s in the help (e.g. "Value" in "(default: Value)")
+            })
+
+
+def at_most_one_from_enum(model_cls, values: Dict[str, Any], enum_cls) -> Dict[str, Any]:
+    """
+    Among the fields of a Pydantic-Argparse model whose ``Field`` definition is
+    tagged with the ``enum`` keyword set to the given ``Enum`` type, ensures
+    that at most one of them has a true value in the given Pydantic-Argparse
+    validator ``values``, or raises a ``ValueError`` otherwise.
+
+    :param model_cls: A Pydantic-Argparse model class.
+    :param values:    The Pydantic-Argparse validator ``values``.
+    :param enum_cls:  The ``Enum`` class the fields of the Pydantic-Argparse
+                      model are tagged with (using the ``enum`` keyword).
+    :return: The ``values`` argument, if no ``ValueError`` has been raised.
+    """
+    enum_names = [field_name for field_name, model_field in model_cls.__fields__.items() if model_field.field_info.extra.get('enum') == enum_cls]
+    ret = [field_name for field_name in enum_names if values.get(field_name)]
+    if (length := len(ret)) > 1:
+        raise ValueError(f'at most one of {', '.join([option_name(enum_name) for enum_name in enum_names])} is allowed, got {length} ({', '.join([option_name(enum_name) for enum_name in ret])})')
+    return values
+
+
+def get_from_enum(model_inst, enum_cls, default=None):
+    """
+    Among the fields of a Pydantic-Argparse model whose ``Field`` definition is
+    tagged with the ``enum`` keyword set to the given ``Enum`` type, gets the
+    corresponding enum value of the first with a true value in the model, or
+    returns the given default value. Assumes the existence of a
+    ``from_member()`` static method in the ``Enum`` class.
+
+    :param model_inst:
+    :param enum_cls:
+    :param default:
+    :return:
+    """
+    enum_names = [field_name for field_name, model_field in type(model_inst).__fields__.items() if model_field.field_info.extra.get('enum') == enum_cls]
+    for field_name in enum_names:
+        if getattr(model_inst, field_name):
+            return enum_cls[field_name]
+    return default
+
+
+def at_most_one(values: Dict[str, Any], *names: str):
+    if (length := _matchy_length(values, *names)) > 1:
+        raise ValueError(f'at most one of {', '.join([option_name(name) for name in names])} is allowed, got {length}')
+    return values
+
+
+def exactly_one(values: Dict[str, Any], *names: str):
+    if (length := _matchy_length(values, *names)) != 1:
+        raise ValueError(f'exactly one of {', '.join([option_name(name) for name in names])} is required, got {length}')
+    return values
+
+
+def one_or_more(values: Dict[str, Any], *names: str):
+    if _matchy_length(values, *names) == 0:
+        raise ValueError(f'one or more of {', '.join([option_name(name) for name in names])} is required')
+    return values
+
+
+def option_name(name: str) -> str:
+    return f'{('-' if len(name) == 1 else '--')}{name.replace('_', '-')}'
+
+
+def _matchy_length(values: Dict[str, Any], *names: str) -> int:
+    return len([name for name in names if values.get(name)])

lockss_pybasic-0.1.0/src/lockss/pybasic/errorutil.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python3
+
+# Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its contributors
+# may be used to endorse or promote products derived from this software without
+# specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+Error and exception utilities.
+"""
+
+class InternalError(RuntimeError):
+    """
+    A simple no-arg ``RuntimeError`` with the message ``internal error``,
+    intended for situations that should never occur.
+    """
+
+    def __init__(self) -> None:
+        """
+        Constructs a new ``InternalError`` instance.
+        """
+        super().__init__('internal error')

lockss_pybasic-0.1.0/src/lockss/pybasic/fileutil.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python3
+
+# Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its contributors
+# may be used to endorse or promote products derived from this software without
+# specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+File and path utilities.
+"""
+
+from pathlib import Path, PurePath
+import sys
+from typing import List, Union
+
+
+def file_lines(fpath: Path) -> List[str]:
+    """
+    Returns a list of lines from the given file, with '#' comments and leading
+    and trailing whitespace removed, ignoring empty lines.
+
+    :param fpath: A ``Path`` to a file, ``-`` for ``sys.stdin``.
+    :type fpath: Path
+    :return: A list of processed lines.
+    :rtype: List[str]
+    """
+    f = None
+    try:
+        f = open(path(fpath), 'r') if fpath != '-' else sys.stdin
+        return [line for line in [line.partition('#')[0].strip() for line in f] if len(line) > 0]
+    finally:
+        if f is not None and path != '-':
+            f.close()
+
+
+def path(purepath_or_string: Union[PurePath, str]) -> Path:
+    """
+    Returns the given ``PurePath`` (or if given a string, the ``Path`` created
+    from that string), expanded with ``expanduser()`` and resolved with
+    ``resolve()``.
+
+    :param purepath_or_string: A ``PurePath`` (or a ``str`` from which to create
+                               a ``Path``).
+    :type purepath_or_string: Union[PurePath, str]
+    :return: An expanded and resolved ``Path``.
+    :rtype: Path
+    """
+    if not issubclass(type(purepath_or_string), PurePath):
+        purepath_or_string = Path(purepath_or_string)
+    return purepath_or_string.expanduser().resolve()

lockss_pybasic-0.1.0/src/lockss/pybasic/outpututil.py

@@ -0,0 +1,57 @@
+#!/usr/bin/env python3
+
+# Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+#
+# 1. Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+#
+# 2. Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+#
+# 3. Neither the name of the copyright holder nor the names of its contributors
+# may be used to endorse or promote products derived from this software without
+# specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+Utilities to work with 'tabulate'.
+"""
+
+from enum import Enum
+
+from pydantic.v1 import BaseModel, Field, validator
+import tabulate
+from typing import Optional
+
+
+OutputFormat = Enum('OutputFormat', tabulate.tabulate_formats)
+
+
+DEFAULT_OUTPUT_FORMAT = 'simple' # from tabulate
+
+
+class OutputFormatOptions(BaseModel):
+    output_format: Optional[str] = Field(DEFAULT_OUTPUT_FORMAT, description=f'[output] set the output format; choices: {', '.join(OutputFormat.__members__.keys())}')
+
+    @validator('output_format')
+    def _validate_output_format(cls, val: str):
+        try:
+            _ = OutputFormat[val]
+            return val
+        except KeyError:
+            raise ValueError(f'must be one of {', '.join(OutputFormat.__members__.keys())}; got {val}')