lockss-pybasic 0.1.0.dev12__py3-none-any.whl → 0.1.0.dev14__py3-none-any.whl

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-dev12'
+__version__ = '0.1.0-dev14'

lockss/pybasic/cliutil.py

@@ -33,109 +33,169 @@ Command line utilities.
 """
 
 from abc import ABC, abstractmethod
+from collections.abc import Callable
 import sys
-from typing import Any, Dict, Generic, List, Optional, TypeVar
+from typing import Any, Dict, Generic, Optional, TypeVar
 
 from pydantic.v1 import BaseModel, Field
 from pydantic_argparse import ArgumentParser
 
 
-class Printable(ABC):
+class ActionCommand(Callable, BaseModel):
+    """
+    Base class for a Pydantic-Argparse command
+    """
+    pass
 
-    def print(self, file=sys.stdout):
-        print(self.get_display(), file=file)
 
-    @abstractmethod
-    def get_display(self):
-        pass
-
-
-class CopyrightCommand:
+class StringCommand(ActionCommand):
 
     @staticmethod
-    def make(copyright):
-        class CopyrightModel(Printable, BaseModel):
-            def get_display(self):
-                return copyright
-        return CopyrightModel
+    def type(display_str: str):
+        class _StringCommand(StringCommand):
+            def __call__(self, file=sys.stdout):
+                print(display_str, file=file)
+        return _StringCommand
 
-    @staticmethod
-    def field():
-        return Field(description='print the copyright and exit')
 
+COPYRIGHT_DESCRIPTION = 'print the copyright and exit'
+LICENSE_DESCRIPTION = 'print the software license and exit'
+VERSION_DESCRIPTION = 'print the version number and exit'
 
-class LicenseCommand:
 
-    @staticmethod
-    def make(license):
-        class LicenseModel(Printable, BaseModel):
-            def get_display(self):
-                return license
-        return LicenseModel
+BaseModelT = TypeVar('BaseModelT', bound=BaseModel)
 
-    @staticmethod
-    def field():
-        return Field(description='print the software license and exit')
 
+class BaseCli(Generic[BaseModelT]):
+    """
+    Base class for general CLI functionality.
 
-class VersionCommand:
+    ``BaseModelT`` represents a Pydantic-Argparse model type deriving from
+    ``BaseModel``.
 
-    @staticmethod
-    def make(version):
-        class VersionModel(Printable, BaseModel):
-            def get_display(self):
-                return version
-        return VersionModel
-
-    @staticmethod
-    def field():
-        return Field(description='print the version number and exit')
+    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, **extra):
+        """
+        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.
+        """
+        super().__init__()
+        self.args: Optional[BaseModelT] = None
+        self.parser: Optional[ArgumentParser] = None
+        self.extra: Dict[str, Any] = dict(**extra)
 
-ModelT = TypeVar('ModelT')
+    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``.
 
-class BaseCli(Generic[ModelT], ABC):
+        *  Stores the Pydantic-Argparse parsed arguemnts in ``self.args``.
 
-    def __init__(self, **extra):
-        super().__init__()
-        self.args: ModelT = None
-        self.parser: ArgumentParser = None
-        self.extra: Dict[str, Any] = dict(**extra)
+        *  Calls ``dispatch()``.
 
-    def run(self):
+        :return: Nothing.
+        """
         self.parser: ArgumentParser = ArgumentParser(model=self.extra.get('model'),
                                                      prog=self.extra.get('prog'),
                                                      description=self.extra.get('description'))
         self.args = self.parser.parse_typed_args()
         self.dispatch()
 
-    @abstractmethod
-    def dispatch(self):
-        pass
+    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``.
+
+        :return: Nothing.
+        """
+        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 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 _matchy_length(values: Dict[str, Any], *names: str) -> int:
-    return len([name for name in names if values.get(name)])
+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:
+    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:
+    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:
+    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):
     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/errorutil.py

@@ -33,6 +33,10 @@ Error and exception utilities.
 """
 
 class InternalError(RuntimeError):
+    """
+    A simple ``RuntimeError`` with the message ``internal error``, intended for
+    situations that should never occur.
+    """
 
     def __init__(self, *args: object) -> None:
         super().__init__('internal error')

lockss/pybasic/fileutil.py

@@ -34,10 +34,17 @@ File and path utilities.
 
 from pathlib import Path, PurePath
 import sys
-from typing import Union
+from typing import List, Union
 
 
-def file_lines(fpath: Path):
+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.
+
+    :param fpath: A ``Path`` to a file (``-`` for ``sys.stdin``).
+    :return:      A list of lines.
+    """
     f = None
     try:
         f = open(path(fpath), 'r') if fpath != '-' else sys.stdin
@@ -47,7 +54,16 @@ def file_lines(fpath: Path):
             f.close()
 
 
-def path(purepath_or_string: Union[PurePath, str]):
+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``).
+    :return:                   An expanded and resolved ``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.dev12.dist-info → lockss_pybasic-0.1.0.dev14.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: lockss-pybasic
-Version: 0.1.0.dev12
+Version: 0.1.0.dev14
 Summary: Basic Python utilities
 License: BSD-3-Clause
 Author: Thib Guicherd-Callin
@@ -13,7 +13,7 @@ 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.3,<3.0.0)
+Requires-Dist: pydantic (>=2.11.0,<3.0.0)
 Requires-Dist: pydantic-argparse (>=0.10.0,<0.11.0)
 Description-Content-Type: text/x-rst
 

lockss_pybasic-0.1.0.dev14.dist-info/RECORD

@@ -0,0 +1,8 @@
+lockss/pybasic/__init__.py,sha256=oNqF2XvMGruAJn3JJJHni3MX72Hwmv9pW9C1YHf2g9A,1679
+lockss/pybasic/cliutil.py,sha256=UK-Z82LWW4t0aJqcqT79E3t6806q0pKREW_Lm_BEdxs,8034
+lockss/pybasic/errorutil.py,sha256=OJqRGOjzKK8_OTJCq77u0_XZ5ti2BoVidk5jSTMB6xg,1882
+lockss/pybasic/fileutil.py,sha256=O_EcxobrHPLeD7lAlvtYOkd0R2NOIvpGK6mZOZTxyG4,2856
+lockss_pybasic-0.1.0.dev14.dist-info/LICENSE,sha256=O9ONND4uDxY_jucI4jZDf2liAk05ScEJaYu-Al7EOdQ,1506
+lockss_pybasic-0.1.0.dev14.dist-info/METADATA,sha256=JjYlda28TysulP8Mu-rAAIvKqDpjqEtWaNw7yYyppJs,696
+lockss_pybasic-0.1.0.dev14.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
+lockss_pybasic-0.1.0.dev14.dist-info/RECORD,,

lockss_pybasic-0.1.0.dev12.dist-info/RECORD

@@ -1,8 +0,0 @@
-lockss/pybasic/__init__.py,sha256=YSnY4g1QwuL_AhsQgTVfznUy6uTQ1uwlFxsgU14IIMA,1679
-lockss/pybasic/cliutil.py,sha256=sPaQ5gZ2Xj6Ld5Ol5AYH5Uh8ahXhvbOjEAbnWPRH7nI,4558
-lockss/pybasic/errorutil.py,sha256=SD0kZtQt_lyVqqlLeo5K6ihkgQ1sm1rtvwI_pST-7ns,1746
-lockss/pybasic/fileutil.py,sha256=hr4RtAaalEKwXx1kjGBReLOcmlbml1cwG9K5zcbreSw,2199
-lockss_pybasic-0.1.0.dev12.dist-info/LICENSE,sha256=O9ONND4uDxY_jucI4jZDf2liAk05ScEJaYu-Al7EOdQ,1506
-lockss_pybasic-0.1.0.dev12.dist-info/METADATA,sha256=-_J0Ua6w6bnUqs88DHBOoV7fqnx4UD_nGxHNrQJ5xX8,696
-lockss_pybasic-0.1.0.dev12.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
-lockss_pybasic-0.1.0.dev12.dist-info/RECORD,,