lockss-pybasic 0.1.0.dev22__tar.gz → 0.2.0.dev1__tar.gz

lockss_pybasic-0.2.0.dev1/CHANGELOG.rst

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

lockss_pybasic-0.2.0.dev1/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.3
+Name: lockss-pybasic
+Version: 0.2.0.dev1
+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.2.0.dev1/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.2.0.dev1/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.2.0-dev1" # 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.dev22 → lockss_pybasic-0.2.0.dev1}/src/lockss/pybasic/__init__.py

@@ -36,4 +36,4 @@ 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-dev22'
+__version__ = '0.2.0-dev1'

{lockss_pybasic-0.1.0.dev22 → lockss_pybasic-0.2.0.dev1}/src/lockss/pybasic/cliutil.py

@@ -41,19 +41,33 @@ 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 command
+    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):
+            def __call__(self, file=sys.stdout, **kwargs):
                 print(display_str, file=file)
         return _StringCommand
 
@@ -78,20 +92,21 @@ class BaseCli(Generic[BaseModelT]):
     method named ``_x_y_z``.
     """
 
-    def __init__(self, **extra):
+    def __init__(self, **kwargs):
         """
-        Makes a new BaseCli instance.
-
-        :param extra: 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.
+        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(**extra)
+        self.extra: Dict[str, Any] = dict(**kwargs)
 
     def run(self) -> None:
         """
@@ -104,8 +119,6 @@ class BaseCli(Generic[BaseModelT]):
         *  Stores the Pydantic-Argparse parsed arguments in ``self.args``.
 
         *  Calls ``dispatch()``.
-
-        :return: Nothing.
         """
         self._parser: ArgumentParser = ArgumentParser(model=self.extra.get('model'),
                                                       prog=self.extra.get('prog'),
@@ -116,33 +129,32 @@ class BaseCli(Generic[BaseModelT]):
 
     def dispatch(self) -> None:
         """
-        Dispatches from the first field ``x_y_z`` in ``self.args`` that is a
+        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``.
-
-        :return: Nothing.
         """
-        field_names = self._args.__class__.__fields__.keys()
+        self._dispatch_recursive(self._args, [])
+
+    def _dispatch_recursive(self, base_model: BaseModel, subcommands: list[str]) -> None:
+        field_names = base_model.__class__.__fields__.keys()
         for field_name in field_names:
-            field_value = getattr(self._args, field_name)
+            field_value = getattr(base_model, 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
+                self._dispatch_recursive(field_value, [*subcommands, field_name])
+                return
+        func_name = ''.join(f'_{sub}' for sub in subcommands)
+        func = getattr(self, func_name)
+        if callable(func):
+            func(base_model) # FIXME?
         else:
-            self._parser.error(f'unknown command; expected one of {', '.join(field_names)}')
+            self._parser.exit(1, f'internal error: no {func_name} callable for the {" ".join(sub for sub in subcommands)}')
 
     def _initialize_rich_argparse(self) -> None:
-        for cls in [RichHelpFormatter]:
-            cls.styles.update({
-                'argparse.args': f'bold {cls.styles["argparse.args"]}',
-                'argparse.groups': f'bold {cls.styles["argparse.groups"]}',
-                'argparse.metavar': f'bold {cls.styles["argparse.metavar"]}',
-                'argparse.prog': f'bold {cls.styles["argparse.prog"]}',
-            })
+        """
+        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'):
@@ -152,6 +164,20 @@ class BaseCli(Generic[BaseModelT]):
                             __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]:
     """
@@ -211,7 +237,7 @@ def one_or_more(values: Dict[str, Any], *names: str):
     return values
 
 
-def option_name(name: str):
+def option_name(name: str) -> str:
     return f'{('-' if len(name) == 1 else '--')}{name.replace('_', '-')}'
 
 

{lockss_pybasic-0.1.0.dev22 → lockss_pybasic-0.2.0.dev1}/src/lockss/pybasic/errorutil.py

@@ -34,9 +34,12 @@ Error and exception utilities.
 
 class InternalError(RuntimeError):
     """
-    A simple ``RuntimeError`` with the message ``internal error``, intended for
-    situations that should never occur.
+    A simple no-arg ``RuntimeError`` with the message ``internal error``,
+    intended for situations that should never occur.
     """
 
-    def __init__(self, *args: object) -> None:
+    def __init__(self) -> None:
+        """
+        Constructs a new ``InternalError`` instance.
+        """
         super().__init__('internal error')

{lockss_pybasic-0.1.0.dev22 → lockss_pybasic-0.2.0.dev1}/src/lockss/pybasic/fileutil.py

@@ -40,10 +40,12 @@ 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
-    trailing whitespace removed, ignoring empty lines.
+    and trailing whitespace removed, ignoring empty lines.
 
-    :param fpath: A ``Path`` to a file (``-`` for ``sys.stdin``).
-    :return:      A list of 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:
@@ -62,7 +64,9 @@ def path(purepath_or_string: Union[PurePath, str]) -> Path:
 
     :param purepath_or_string: A ``PurePath`` (or a ``str`` from which to create
                                a ``Path``).
-    :return:                   An expanded and resolved ``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)

{lockss_pybasic-0.1.0.dev22 → lockss_pybasic-0.2.0.dev1}/src/lockss/pybasic/outpututil.py

@@ -32,10 +32,8 @@
 Utilities to work with 'tabulate'.
 """
 
-
 from enum import Enum
 
-
 from pydantic.v1 import BaseModel, Field, validator
 import tabulate
 from typing import Optional

lockss_pybasic-0.1.0.dev22/PKG-INFO

@@ -1,22 +0,0 @@
-Metadata-Version: 2.3
-Name: lockss-pybasic
-Version: 0.1.0.dev22
-Summary: Basic Python utilities
-License: BSD-3-Clause
-Author: Thib Guicherd-Callin
-Author-email: thib@cs.stanford.edu
-Requires-Python: >=3.9,<4.0
-Classifier: License :: OSI Approved :: BSD License
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-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)
-Description-Content-Type: text/x-rst
-
-

lockss_pybasic-0.1.0.dev22/pyproject.toml

@@ -1,25 +0,0 @@
-[project]
-name = "lockss-pybasic"
-version = "0.1.0-dev22"
-description = "Basic Python utilities"
-authors = [
-    { name = "Thib Guicherd-Callin", email = "thib@cs.stanford.edu" }
-]
-license = { text = "BSD-3-Clause" }
-readme = "README.rst"
-requires-python = ">=3.9,<4.0"
-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)"
-]
-
-[tool.poetry]
-packages = [
-    { include = "lockss", from = "src" }
-]
-
-[build-system]
-requires = ["poetry-core>=2.0.0,<3.0.0"]
-build-backend = "poetry.core.masonry.api"