lockss-pybasic 0.1.0.dev23__py3-none-any.whl → 0.2.0__py3-none-any.whl

lockss/pybasic/__init__.py

@@ -5,7 +5,7 @@ Basic Python utilities.
 """
 
 __copyright__ = '''
-Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+Copyright (c) 2000-2026, Board of Trustees of Leland Stanford Jr. University
 '''.strip()
 
 __license__ = __copyright__ + '\n\n' + '''
@@ -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-dev23'
+__version__ = '0.2.0'

lockss/pybasic/auidutil.py

@@ -0,0 +1,417 @@
+#!/usr/bin/env python3
+
+# Copyright (c) 2000-2026, 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 AUID Generator
+
+Port of the AUID generation logic from org.lockss.plugin.PluginManager
+and related utility classes in the LOCKSS lockss-core library.
+"""
+
+import urllib.parse
+from typing import Dict
+
+
+class InvalidAuidError(ValueError):
+    """Raised when an AUID string is malformed or invalid."""
+    pass
+
+
+class AuidGenerator:
+    """
+    Generator for LOCKSS Archival Unit Identifiers (AUIDs).
+
+    This class provides static methods for generating and parsing AUIDs,
+    which uniquely identify archival units in the LOCKSS system.
+
+    AUID Format: pluginKey&auKey
+    - pluginKey: Plugin class name with dots replaced by pipes
+    - auKey: Canonically encoded definitional parameters
+
+    Example:
+        >>> plugin_id = "org.lockss.plugin.simulated.SimulatedPlugin"
+        >>> params = {"base_url": "http://example.com/", "year": "2023"}
+        >>> auid = AuidGenerator.generate_auid(plugin_id, params)
+        >>> print(auid)
+        org|lockss|plugin|simulated|SimulatedPlugin&base_url~http%3A%2F%2Fexample%2Ecom%2F&year~2023
+    """
+
+    @staticmethod
+    def plugin_key_from_id(plugin_id: str) -> str:
+        """
+        Convert plugin ID to plugin key by replacing dots with pipes.
+
+        Port of PluginManager.pluginKeyFromId()
+
+        Args:
+            plugin_id: Plugin class name (e.g., "org.lockss.plugin.simulated.SimulatedPlugin")
+
+        Returns:
+            Plugin key (e.g., "org|lockss|plugin|simulated|SimulatedPlugin")
+
+        Example:
+            >>> AuidGenerator.plugin_key_from_id("org.lockss.plugin.TestPlugin")
+            'org|lockss|plugin|TestPlugin'
+        """
+        if not plugin_id:
+            raise ValueError("plugin_id cannot be empty")
+        return plugin_id.replace(".", "|")
+
+    @staticmethod
+    def plugin_id_from_key(plugin_key: str) -> str:
+        """
+        Convert plugin key back to plugin ID by replacing pipes with dots.
+
+        Args:
+            plugin_key: Plugin key (e.g., "org|lockss|plugin|simulated|SimulatedPlugin")
+
+        Returns:
+            Plugin ID (e.g., "org.lockss.plugin.simulated.SimulatedPlugin")
+
+        Example:
+            >>> AuidGenerator.plugin_id_from_key("org|lockss|plugin|TestPlugin")
+            'org.lockss.plugin.TestPlugin'
+        """
+        if not plugin_key:
+            raise ValueError("plugin_key cannot be empty")
+        return plugin_key.replace("|", ".")
+
+    # Characters that don't need encoding - matches Java PropKeyEncoder exactly
+    # See lockss-core PropKeyEncoder.java lines 46-62
+    _DONT_NEED_ENCODING = set(
+        'abcdefghijklmnopqrstuvwxyz'
+        'ABCDEFGHIJKLMNOPQRSTUVWXYZ'
+        '0123456789'
+        ' '  # Space is converted to '+' in encode()
+        '-'
+        '_'
+        '*'
+    )
+
+    @staticmethod
+    def encode_component(s: str) -> str:
+        """
+        URL-encode a string component for use in AUID.
+
+        Port of PropKeyEncoder.encode() from lockss-core.
+
+        This method encodes strings using URL encoding with the following rules:
+        - Alphanumeric characters (a-z, A-Z, 0-9) are not encoded
+        - Hyphens (-), underscores (_), and asterisks (*) are not encoded
+        - Spaces are encoded as '+'
+        - All other characters (including periods) are percent-encoded with uppercase hex digits
+
+        Note: This differs from standard URL encoding (RFC 3986) which treats
+        periods (.) as unreserved. Java's PropKeyEncoder encodes periods.
+
+        Args:
+            s: String to encode
+
+        Returns:
+            URL-encoded string with spaces as '+' and uppercase hex digits
+
+        Example:
+            >>> AuidGenerator.encode_component("http://example.com/")
+            'http%3A%2F%2Fexample%2Ecom%2F'
+        """
+        if not s:
+            return ""
+
+        result = []
+        # Encode string to UTF-8 bytes, matching Java's OutputStreamWriter behavior
+        for char in s:
+            if char in AuidGenerator._DONT_NEED_ENCODING:
+                if char == ' ':
+                    result.append('+')
+                else:
+                    result.append(char)
+            else:
+                # Encode character to UTF-8 bytes and percent-encode each byte
+                char_bytes = char.encode('utf-8')
+                for byte in char_bytes:
+                    result.append('%')
+                    result.append(format(byte, '02X'))
+
+        return ''.join(result)
+
+    @staticmethod
+    def decode_component(s: str) -> str:
+        """
+        URL-decode a string component from an AUID.
+
+        Args:
+            s: URL-encoded string
+
+        Returns:
+            Decoded string
+
+        Example:
+            >>> AuidGenerator.decode_component('http%3A%2F%2Fexample.com%2F')
+            'http://example.com/'
+        """
+        if not s:
+            return ""
+        return urllib.parse.unquote_plus(s, errors="strict")
+
+    @staticmethod
+    def props_to_canonical_encoded_string(props: Dict[str, str]) -> str:
+        """
+        Convert properties dictionary to canonical encoded string.
+
+        Port of PropUtil.propsToCanonicalEncodedString() from lockss-core.
+
+        The canonical form is created by:
+        1. Sorting keys alphabetically
+        2. Encoding each key and value
+        3. Joining with '~' between key and value, '&' between pairs
+
+        Args:
+            props: Dictionary of AU definitional parameters
+
+        Returns:
+            Canonical encoded string (e.g., "key1~val1&key2~val2")
+
+        Example:
+            >>> props = {"year": "2023", "base_url": "http://example.com/"}
+            >>> AuidGenerator.props_to_canonical_encoded_string(props)
+            'base_url~http%3A%2F%2Fexample.com%2F&year~2023'
+        """
+        if not props:
+            return ""
+
+        # Sort keys for canonical ordering (case-sensitive, like Java TreeSet)
+        sorted_keys = sorted(props.keys())
+
+        parts = []
+        for key in sorted_keys:
+            val = props[key]
+            if val is None:
+                val = ""
+            encoded_key = AuidGenerator.encode_component(str(key))
+            encoded_val = AuidGenerator.encode_component(str(val))
+            parts.append(f"{encoded_key}~{encoded_val}")
+
+        return "&".join(parts)
+
+    @staticmethod
+    def canonical_encoded_string_to_props(encoded: str) -> Dict[str, str]:
+        """
+        Decode a canonical encoded string back to properties dictionary.
+
+        Args:
+            encoded: Canonical encoded string (e.g., "key1~val1&key2~val2")
+
+        Returns:
+            Dictionary of decoded parameters
+
+        Example:
+            >>> encoded = 'base_url~http%3A%2F%2Fexample.com%2F&year~2023'
+            >>> AuidGenerator.canonical_encoded_string_to_props(encoded)
+            {'base_url': 'http://example.com/', 'year': '2023'}
+        """
+        if not encoded:
+            return {}
+
+        props = {}
+        pairs = encoded.split("&")
+
+        for pair in pairs:
+            if "~" not in pair:
+                raise ValueError("Missing tilde in key-value pair")
+            key_encoded, val_encoded = pair.split("~", 1)
+            if "~" in val_encoded:
+                raise ValueError("Additional tilde in key-value pair")
+            key = AuidGenerator.decode_component(key_encoded)
+            val = AuidGenerator.decode_component(val_encoded)
+            props[key] = val
+
+        return props
+
+    @staticmethod
+    def generate_auid(plugin_id: str, au_def_props: Dict[str, str]) -> str:
+        """
+        Generate an AUID from plugin ID and definitional properties.
+
+        Port of PluginManager.generateAuId() from lockss-core.
+
+        Args:
+            plugin_id: Plugin class name (e.g., "org.lockss.plugin.simulated.SimulatedPlugin")
+            au_def_props: Dictionary of AU definitional parameters
+
+        Returns:
+            AUID string (e.g., "org|lockss|plugin|simulated|SimulatedPlugin&base_url~...")
+
+        Raises:
+            ValueError: If plugin_id is empty
+
+        Example:
+            >>> plugin_id = "org.lockss.plugin.simulated.SimulatedPlugin"
+            >>> params = {"base_url": "http://example.com/", "year": "2023"}
+            >>> AuidGenerator.generate_auid(plugin_id, params)
+            'org|lockss|plugin|simulated|SimulatedPlugin&base_url~http%3A%2F%2Fexample.com%2F&year~2023'
+        """
+        if not plugin_id:
+            raise ValueError("plugin_id cannot be empty")
+
+        plugin_key = AuidGenerator.plugin_key_from_id(plugin_id)
+        au_key = AuidGenerator.props_to_canonical_encoded_string(au_def_props)
+        return f"{plugin_key}&{au_key}"
+
+    @staticmethod
+    def plugin_key_from_auid(auid: str) -> str:
+        """
+        Extract plugin key from AUID.
+
+        Port of PluginManager.pluginKeyFromAuId() from lockss-core.
+
+        Args:
+            auid: AUID string
+
+        Returns:
+            Plugin key portion
+
+        Raises:
+            InvalidAuidError: If AUID format is invalid
+
+        Example:
+            >>> auid = "org|lockss|plugin|TestPlugin&base_url~http%3A%2F%2Fexample.com%2F"
+            >>> AuidGenerator.plugin_key_from_auid(auid)
+            'org|lockss|plugin|TestPlugin'
+        """
+        if not auid:
+            raise InvalidAuidError("AUID cannot be empty")
+
+        idx = auid.find("&")
+        if idx < 0:
+            raise InvalidAuidError(f"AUID missing '&' separator: {auid}")
+
+        return auid[:idx]
+
+    @staticmethod
+    def au_key_from_auid(auid: str) -> str:
+        """
+        Extract AU key from AUID.
+
+        Port of PluginManager.auKeyFromAuId() from lockss-core.
+
+        Args:
+            auid: AUID string
+
+        Returns:
+            AU key portion (may be empty string)
+
+        Raises:
+            InvalidAuidError: If AUID format is invalid
+
+        Example:
+            >>> auid = "org|lockss|plugin|TestPlugin&base_url~http%3A%2F%2Fexample.com%2F"
+            >>> AuidGenerator.au_key_from_auid(auid)
+            'base_url~http%3A%2F%2Fexample.com%2F'
+        """
+        if not auid:
+            raise InvalidAuidError("AUID cannot be empty")
+
+        idx = auid.find("&")
+        if idx < 0:
+            raise InvalidAuidError(f"AUID missing '&' separator: {auid}")
+
+        return auid[idx + 1:]
+
+    @staticmethod
+    def plugin_id_from_auid(auid: str) -> str:
+        """
+        Extract plugin ID from AUID.
+
+        Port of PluginManager.pluginIdFromAuId() from lockss-core.
+
+        Args:
+            auid: AUID string
+
+        Returns:
+            Plugin ID (with dots restored)
+
+        Raises:
+            InvalidAuidError: If AUID format is invalid
+
+        Example:
+            >>> auid = "org|lockss|plugin|TestPlugin&base_url~http%3A%2F%2Fexample.com%2F"
+            >>> AuidGenerator.plugin_id_from_auid(auid)
+            'org.lockss.plugin.TestPlugin'
+        """
+        plugin_key = AuidGenerator.plugin_key_from_auid(auid)
+        return AuidGenerator.plugin_id_from_key(plugin_key)
+
+    @staticmethod
+    def decode_auid(auid: str) -> Dict[str, str]:
+        """
+        Decode an AUID into its definitional parameters.
+
+        This is a convenience method that extracts the AU key and decodes it.
+
+        Args:
+            auid: AUID string
+
+        Returns:
+            Dictionary of decoded AU parameters
+
+        Raises:
+            InvalidAuidError: If AUID format is invalid
+
+        Example:
+            >>> auid = "org|lockss|plugin|TestPlugin&base_url~http%3A%2F%2Fexample.com%2F&year~2023"
+            >>> AuidGenerator.decode_auid(auid)
+            {'base_url': 'http://example.com/', 'year': '2023'}
+        """
+        au_key = AuidGenerator.au_key_from_auid(auid)
+        return AuidGenerator.canonical_encoded_string_to_props(au_key)
+
+    @staticmethod
+    def validate_auid(auid: str) -> bool:
+        """
+        Check if an AUID string is valid.
+
+        Args:
+            auid: AUID string to validate
+
+        Returns:
+            True if valid, False otherwise
+
+        Example:
+            >>> AuidGenerator.validate_auid("org|lockss|plugin|TestPlugin&base_url~http%3A%2F%2Fexample.com%2F")
+            True
+            >>> AuidGenerator.validate_auid("invalid-auid")
+            False
+        """
+        try:
+            AuidGenerator.plugin_key_from_auid(auid)
+            AuidGenerator.au_key_from_auid(auid)
+            return True
+        except (InvalidAuidError, ValueError):
+            return False

lockss/pybasic/cliutil.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-# Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+# Copyright (c) 2000-2026, 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:
@@ -32,211 +32,205 @@
 Command line utilities.
 """
 
-from collections.abc import Callable
-import sys
-from typing import Any, Dict, Generic, Optional, TypeVar
+from pathlib import Path
+from typing import Any, Optional, Union
 
-from pydantic.v1 import BaseModel
-from pydantic_argparse import ArgumentParser
-from pydantic_argparse.argparse.actions import SubParsersAction
-from rich_argparse import RichHelpFormatter
+import click
+from click.types import ParamType, IntRange
+from click_extra import ChoiceSource, EnumChoice, ExtraContext, HelpExtraFormatter, Style, TableFormat, option
+from click_extra.colorize import default_theme
 
 
-class ActionCommand(Callable, BaseModel):
+def click_path(spec: Optional[str]) -> click.Path:
     """
-    Base class for a pydantic-argparse style command.
+    Generates a ``click.Path`` based on a specification string.
+
+    The specification string can contain the following specifier characters:
+
+    .. list-table::
+       :header-rows: 1
+
+       *  *  Specifier
+          *  Present
+          *  Mutually exclusive with
+       *  *  ``f``
+          *  Must be a file
+          *  ``d`` [*]
+       *  *  ``d``
+          *  Must be a directory
+          *  ``f`` [*]
+       *  *  ``e``
+          *  File or directory must exist
+          *  ``E``
+       *  *  ``E``
+          *  File or directory may or may not exist, but if it does not exist,
+             other checks are skipped (default)
+          *  ``e``
+       *  *  ``r``
+          *  File or directory must be readable
+          *
+       *  *  ``w``
+          *  File or directory must be writable
+          *
+       *  *  ``x``
+          *  File or directory must be executable
+          *
+       *  *  ``p``
+          *  Resulting path will be ``pathlib.Path`` (default)
+          *  ``s``
+       *  *  ``s``
+          *  Resulting path will be ``str``
+          *  ``p``
+       *  *  ``-``
+          *  Path is allowed to be ``-``
+          *
+       *  *  ``z``
+          *  Path will be absolute and resolved, with ``pathlib.Path.resolve``
+          *
+
+    When two mutual exclusive specifiers are present, ``ValueError`` is raised.
+
+    :param spec: A specification string.
+    :type spec: str
+    :return: A ``click.Path``.
+    :rtype: click.Path
+    :raises ValueError: If two mutually exclusive specifiers are present in the
+                        specification string.
     """
-    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``.
+    if spec is None:
+        spec = ''
+    allow_dash = False
+    dir_okay = True
+    executable = False
+    exists = False
+    file_okay = True
+    path_type = Path
+    readable = True
+    resolve_path = False
+    writable = False
+    for char in spec:
+        if char == 'd':
+            if 'f' in spec:
+                raise ValueError(f'"d" and "f" are mutually exclusive: {spec}')
+            dir_okay = True
+            file_okay = False
+        elif char == 'e':
+            if 'E' in spec:
+                raise ValueError(f'"e" and "E" are mutually exclusive: {spec}')
+            exists = True
+        elif char == 'E':
+            if 'e' in spec:
+                raise ValueError(f'"E" and "e" are mutually exclusive: {spec}')
+            exists = False
+        elif char == 'f':
+            if 'd' in spec:
+                raise ValueError(f'"f" and "d" are mutually exclusive: {spec}')
+            dir_okay = False
+            file_okay = True
+        elif char == 'p':
+            if 's' in spec:
+                raise ValueError(f'"p" and "s" are mutually exclusive: {spec}')
+            path_type = Path
+        elif char == 'r':
+            readable = True
+        elif char == 's':
+            if 'p' in spec:
+                raise ValueError(f'"s" and "p" are mutually exclusive: {spec}')
+            path_type = str
+        elif char == 'w':
+            writable = True
+        elif char == 'x':
+            executable = True
+        elif char == 'z':
+            resolve_path = True
+        elif char == '-':
+            allow_dash = True
+        else:
+            raise ValueError(f'unknown specification character "{char}": {spec}')
+    return click.Path(allow_dash=allow_dash,
+                      dir_okay=dir_okay,
+                      executable=executable,
+                      exists=exists,
+                      file_okay=file_okay,
+                      path_type=path_type,
+                      readable=readable,
+                      resolve_path=resolve_path,
+                      writable=writable)
+
+
+#: Composes the given decorators, so that
+#:     @compose_decorators(f, g, h)
+#:     def foo():
+#:         pass
+#: is equivalent to:
+#:     @f
+#      @g
+#      @h
+#:     def foo():
+#:         pass
+def compose_decorators(*decorators):
+    def wrapped(decorated):
+        for dec in reversed(decorators):
+            decorated = dec(decorated)
+        return decorated
+    return wrapped
+
+
+def make_table_format_option(switches: Union[str, tuple[str, ...]] = ('--table-format', '-T'),
+                             default: TableFormat = TableFormat.SIMPLE):
     """
-
-    @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]):
+    Makes an equivalent of ``click_Extra.table_format_option`` with the given
+    command line switches and the given table format default.
+
+    The standard ``click_Extra.table_format_option`` attaches to the top-level
+    command only.
+
+    :param switches: A string or tuple of strings for the command line switches.
+    :type switches: Union[str, tuple[str, ...]]
+    :param default: A ``click_extra.TableFormat`` default.
+    :type default: TableFormat
+    :return: A remixed ``click_Extra.table_format_option``.
+    :rtype:
     """
-    Base class for general CLI functionality.
+    if type(switches) == str:
+        switches = (switches,)
+    return option(*switches, type=EnumChoice(TableFormat, choice_source=ChoiceSource.VALUE), default=default, show_default=True, help='Set the rendering of tables to the given style.')
 
-    ``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 make_extra_context_settings() -> dict[str, Any]:
     """
+    Makes a custom ``click_Extra.ExtraContext`` with essential changes.
 
-    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
+    Currently, the only change is that the help formatter styles the invoked
+    command in bold.
 
-
-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:
+    :return: A custom ``click_Extra.ExtraContext``.
+    :rtype: dict[str, Any]
     """
-    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
+    return ExtraContext.settings(
+        formatter_settings=HelpExtraFormatter.settings(
+            theme=default_theme.with_(
+                invoked_command=Style(bold=True)
+            )
+        )
+    )
 
 
-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
+#: A ``click.ParamType`` for strictly positive integers (1 to infinity).
+PositiveInt: ParamType = IntRange(min=1, max=None)
 
 
-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
+#: A ``click.ParamType`` for non-negative integers (0 to infinity).
+NonNegativeInt: ParamType = IntRange(min=0, max=None)
 
 
-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
+#: A ``click.ParamType`` for strictly negative integers (negative infinity to -1).
+NegativeInt: ParamType = IntRange(min=None, max=-1)
 
 
-def option_name(name: str) -> str:
-    return f'{('-' if len(name) == 1 else '--')}{name.replace('_', '-')}'
+#: A ``click.ParamType`` for non-positive integers (negative infinity to 0).
+NonPositiveInt: ParamType = IntRange(min=None, max=0)
 
 
-def _matchy_length(values: Dict[str, Any], *names: str) -> int:
-    return len([name for name in names if values.get(name)])
+#: A ``click.ParamType`` for unsigned 16-bit integers (0 to 65535).
+UInt16: ParamType = IntRange(min=0, max=65535)

lockss/pybasic/errorutil.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-# Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+# Copyright (c) 2000-2026, 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:

lockss/pybasic/fileutil.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python3
 
-# Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+# Copyright (c) 2000-2026, 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:

lockss_pybasic-0.2.0.dist-info/METADATA

@@ -0,0 +1,68 @@
+Metadata-Version: 2.4
+Name: lockss-pybasic
+Version: 0.2.0
+Summary: Basic Python utilities
+License: BSD-3-Clause
+License-File: LICENSE
+Author: Thib Guicherd-Callin
+Author-email: thib@cs.stanford.edu
+Maintainer: Thib Guicherd-Callin
+Maintainer-email: thib@cs.stanford.edu
+Requires-Python: >=3.10,<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: click-extra (>=7.5.0,<7.6.0)
+Project-URL: Repository, https://github.com/lockss/lockss-pybasic
+Description-Content-Type: text/x-rst
+
+==============
+lockss-pybasic
+==============
+
+.. |RELEASE| replace:: 0.2.0
+.. |RELEASE_DATE| replace:: 2026-03-18
+
+**Latest release:** |RELEASE| (|RELEASE_DATE|)
+
+``lockss-pybasic`` provides basic utilities for various LOCKSS projects written in Python.
+
+-------
+Modules
+-------
+
+``lockss.pybasic.cliutil``
+   Command line utilities based on `Click Extra <https://kdeldycke.github.io/click-extra>`_, `Cloup <https://cloup.readthedocs.io/>`_ and `Click <https://click.palletsprojects.com/>`_.
+
+   *  ``click_path()``: a ``click.Path`` utility.
+
+   *  ``PositiveInt``, ``NonNegativeInt``, ``NegativeInt``, ``NonPositiveInt``, ``UInt16``: ``click.ParamType`` integer types.
+
+   *  ``compose_decorators()``: a decorator utility.
+
+   *  ``make_table_format_option()``: a remix of ``click_extra.table_format_option`` that is not attached to the top-level command.
+
+   *  ``make_extra_context_settings()``: a custom ``click_extra.ExtraContext``.
+
+``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.
+
+-------------
+Release Notes
+-------------
+
+See `<CHANGELOG.rst>`_.
+

lockss_pybasic-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+lockss/pybasic/__init__.py,sha256=mfug98GqR17NB7OSpPd9mj_-YSAf_0Ij2Ek8fpOSMqc,1673
+lockss/pybasic/auidutil.py,sha256=Q4vjjGfymiXVwPu35RyyLZBnViv8mDJKCjOyJb-sbS8,13921
+lockss/pybasic/cliutil.py,sha256=F970MhLcQCYS3INLQT1Ij8nKt_ICmttiS3nSnuWuN7s,8106
+lockss/pybasic/errorutil.py,sha256=4EaO0a1yIG1DbWltASeT15bg1bGg5kOYspsW0iJdVLc,1951
+lockss/pybasic/fileutil.py,sha256=IIS2AFDgYtmBLPVHqQi1AkIFj6da04b6NQtjX9bIVqQ,2958
+lockss_pybasic-0.2.0.dist-info/METADATA,sha256=UzEx0lIH3DPlaXzpAVJ5AjTZFNqByz_tdaol1vEp3dc,2229
+lockss_pybasic-0.2.0.dist-info/WHEEL,sha256=zp0Cn7JsFoX2ATtOhtaFYIiE2rmFAD4OcMhtUki8W3U,88
+lockss_pybasic-0.2.0.dist-info/licenses/LICENSE,sha256=EOxPunNz3XP6AjgbPFolu-d9BS_AF9TtKn1WXgeYPsE,1506
+lockss_pybasic-0.2.0.dist-info/RECORD,,

{lockss_pybasic-0.1.0.dev23.dist-info → lockss_pybasic-0.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.1.3
+Generator: poetry-core 2.2.1
 Root-Is-Purelib: true
 Tag: py3-none-any

{lockss_pybasic-0.1.0.dev23.dist-info → lockss_pybasic-0.2.0.dist-info/licenses}/LICENSE

@@ -1,4 +1,4 @@
-Copyright (c) 2000-2025, Board of Trustees of Leland Stanford Jr. University
+Copyright (c) 2000-2026, 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:

lockss/pybasic/outpututil.py

@@ -1,57 +0,0 @@
-#!/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}')

lockss_pybasic-0.1.0.dev23.dist-info/METADATA

@@ -1,102 +0,0 @@
-Metadata-Version: 2.3
-Name: lockss-pybasic
-Version: 0.1.0.dev23
-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: Intended Audience :: System Administrators
-Classifier: License :: OSI Approved :: BSD License
-Classifier: Programming Language :: Python
-Classifier: Topic :: Software Development :: Libraries
-Classifier: Topic :: System :: Archiving
-Classifier: Topic :: Utilities
-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-dev23
-.. |RELEASE_DATE| replace:: ?
-
-**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.dev23.dist-info/RECORD

@@ -1,9 +0,0 @@
-lockss/pybasic/__init__.py,sha256=jmOhJI5PiH3jLMWLGSCBYvv8hV2yG9PTPUfvYGtP1oU,1679
-lockss/pybasic/cliutil.py,sha256=Q7WNFbtZzMBfEXjhqsUJlYOdsKYQm0Mgerf7aVe5VK8,10347
-lockss/pybasic/errorutil.py,sha256=XI84PScZ851_-gfoazivJ8ceieMYWaxQr7qih5ltga0,1951
-lockss/pybasic/fileutil.py,sha256=BpdoPWL70xYTuhyQRBEurScRVnPQg0mX-XW8yyKPGjw,2958
-lockss/pybasic/outpututil.py,sha256=JyXKXlkaCcCGvonUvmDGRdI6PxwN5t7DPVIk64S8-2g,2345
-lockss_pybasic-0.1.0.dev23.dist-info/LICENSE,sha256=O9ONND4uDxY_jucI4jZDf2liAk05ScEJaYu-Al7EOdQ,1506
-lockss_pybasic-0.1.0.dev23.dist-info/METADATA,sha256=viCY_etc3kouRMBzEAcl44-zfDWo2Fkzk767I91jBKM,4372
-lockss_pybasic-0.1.0.dev23.dist-info/WHEEL,sha256=b4K_helf-jlQoXBBETfwnf4B04YC67LOev0jo4fX5m8,88
-lockss_pybasic-0.1.0.dev23.dist-info/RECORD,,