lockss-pybasic 0.1.0.dev13__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-dev13'
+__version__ = '0.1.0-dev14'

lockss/pybasic/cliutil.py

@@ -33,6 +33,7 @@ Command line utilities.
 """
 
 from abc import ABC, abstractmethod
+from collections.abc import Callable
 import sys
 from typing import Any, Dict, Generic, Optional, TypeVar
 
@@ -40,11 +41,11 @@ from pydantic.v1 import BaseModel, Field
 from pydantic_argparse import ArgumentParser
 
 
-class ActionCommand(ABC, BaseModel):
-
-    @abstractmethod
-    def action(self):
-        pass
+class ActionCommand(Callable, BaseModel):
+    """
+    Base class for a Pydantic-Argparse command
+    """
+    pass
 
 
 class StringCommand(ActionCommand):
@@ -52,7 +53,7 @@ class StringCommand(ActionCommand):
     @staticmethod
     def type(display_str: str):
         class _StringCommand(StringCommand):
-            def action(self, file=sys.stdout):
+            def __call__(self, file=sys.stdout):
                 print(display_str, file=file)
         return _StringCommand
 
@@ -66,48 +67,111 @@ 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, **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)
 
-    def run(self):
+    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 arguemnts in ``self.args``.
+
+        *  Calls ``dispatch()``.
+
+        :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()
 
-    def dispatch(self):
+    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}')
-                func(field_value)
+                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):
+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 = list()
-    for field_name in enum_names:
-        if values.get(field_name):
-            ret.append(field_name)
+    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 {', '.join([option_name(enum_name) for enum_name in ret])}')
+        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):
-    enum_names = [field_name for field_name, model_field in model_inst.__class__.__fields__.items() if model_field.field_info.extra.get('enum') == enum_cls]
+    """
+    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.from_member(field_name)
+            return enum_cls[field_name]
     return default
 
 

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.dev13.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.dev13
+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.dev13.dist-info/RECORD

@@ -1,8 +0,0 @@
-lockss/pybasic/__init__.py,sha256=YMxnE1BYFx_4jKjWJqU0JUAYBV_PyFw79GwtM0x51gY,1679
-lockss/pybasic/cliutil.py,sha256=dV1l3jlZy0j49eR1UuOCIYh5nTjvlAUwErXE8ufkxL0,5343
-lockss/pybasic/errorutil.py,sha256=SD0kZtQt_lyVqqlLeo5K6ihkgQ1sm1rtvwI_pST-7ns,1746
-lockss/pybasic/fileutil.py,sha256=hr4RtAaalEKwXx1kjGBReLOcmlbml1cwG9K5zcbreSw,2199
-lockss_pybasic-0.1.0.dev13.dist-info/LICENSE,sha256=O9ONND4uDxY_jucI4jZDf2liAk05ScEJaYu-Al7EOdQ,1506
-lockss_pybasic-0.1.0.dev13.dist-info/METADATA,sha256=ts5VSdrLufRNOOn-HueYprKw2owTj8q4N1HY97XQ5eE,696
-lockss_pybasic-0.1.0.dev13.dist-info/WHEEL,sha256=fGIA9gx4Qxk2KDKeNJCbOEwSrmLtjWCwzBz351GyrPQ,88
-lockss_pybasic-0.1.0.dev13.dist-info/RECORD,,