cli-command-parser 2024.5.18.post1__tar.gz → 2024.5.31__tar.gz

{cli_command_parser-2024.5.18.post1/lib/cli_command_parser.egg-info → cli_command_parser-2024.5.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cli_command_parser
-Version: 2024.5.18.post1
+Version: 2024.5.31
 Summary: CLI Command Parser
 Home-page: https://github.com/dskrypa/cli_command_parser
 Author: Doug Skrypa

{cli_command_parser-2024.5.18.post1 → cli_command_parser-2024.5.31}/lib/cli_command_parser/__version__.py

@@ -1,7 +1,7 @@
 __title__ = 'cli_command_parser'
 __description__ = 'CLI Command Parser'
 __url__ = 'https://github.com/dskrypa/cli_command_parser'
-__version__ = '2024.05.18-1'
+__version__ = '2024.05.31'
 __author__ = 'Doug Skrypa'
 __author_email__ = 'dskrypa@gmail.com'
 __license__ = 'Apache 2.0'

{cli_command_parser-2024.5.18.post1 → cli_command_parser-2024.5.31}/lib/cli_command_parser/commands.py

@@ -29,9 +29,6 @@ Argv = Sequence[str]
 class Command(ABC, metaclass=CommandMeta):
     """The main class that other Commands should extend."""
 
-    # TODO: Make the distinction between help/description clearer, or merge them?
-    # TODO: Pull help text from docstring for subcommands if not specified as help=?
-
     #: The parsing Context used for this Command. Provided here for convenience - this reference to it is not used by
     #: any CLI Command Parser internals, so it is safe for subclasses to redefine / overwrite it.
     ctx: Context

{cli_command_parser-2024.5.18.post1 → cli_command_parser-2024.5.31}/lib/cli_command_parser/core.py

@@ -94,11 +94,14 @@ class CommandMeta(ABCMeta, type):
             namespace['_CommandMeta__config'] = config
 
         cls = super().__new__(mcs, name, bases, namespace, **kwargs)
+        if metadata:
+            # If no overrides were provided, then this is skipped, and it will be initialized lazily later
+            # This must be set before calling _maybe_register_sub_cmd so overrides are available during registration
+            cls.__metadata = ProgramMetadata.for_command(cls, parent=mcs._from_parent(mcs.meta, bases), **metadata)
+
         if ABC not in bases:
             mcs._commands.add(cls)
             mcs._maybe_register_sub_cmd(cls, choice, choices, help)
-        if metadata:  # If no overrides were provided, then initialize lazily later
-            cls.__metadata = ProgramMetadata.for_command(cls, parent=mcs._from_parent(mcs.meta, bases), **metadata)
 
         return cls
 

{cli_command_parser-2024.5.18.post1 → cli_command_parser-2024.5.31}/lib/cli_command_parser/inputs/files.py

@@ -11,7 +11,7 @@ from abc import ABC
 from pathlib import Path as _Path
 from typing import Optional, Union
 
-from ..typing import Bool, Converter, PathLike, T
+from ..typing import FP, Bool, Converter, PathLike, T
 from .base import InputType
 from .exceptions import InputValidationError
 from .utils import FileWrapper, InputParam, StatMode, allows_write, fix_windows_path
@@ -188,6 +188,11 @@ class Serialized(File):
         self.converter = converter
         self.pass_file = pass_file
 
+    def __repr__(self) -> str:
+        non_defaults = ', '.join(f'{k}={v!r}' for k, v in self.__dict__.items() if k != 'converter')
+        # `converter` must be excluded to prevent infinite recursion when an instance method is stored in that attr
+        return f'<{self.__class__.__name__}({non_defaults})>'
+
     def _prep_file_wrapper(self, path: _Path) -> FileWrapper:
         return FileWrapper(path, self.mode, self.encoding, self.errors, self.converter, self.pass_file, self.parents)
 
@@ -197,14 +202,28 @@ class Json(Serialized):
     :param kwargs: Additional keyword arguments to pass to :class:`.File`
     """
 
-    def __init__(self, *, mode: str = 'rb', **kwargs):
+    def __init__(self, *, mode: str = 'rb', wrap_errors: bool = True, **kwargs):
         import json
 
-        # TODO: catch JSONDecodeError and provide a standardized cleaner error message (with a way to disable this error handling)
-
         write = allows_write(mode, True)
-        kwargs['pass_file'] = write  # json.load just calls loads with f.read()
-        super().__init__(json.dump if write else json.loads, mode=mode, **kwargs)
+        kwargs['pass_file'] = True
+        super().__init__(json.dump if write else self._load_json, mode=mode, **kwargs)
+        self.wrap_errors = wrap_errors
+
+    def _load_json(self, f: FP):
+        from json import JSONDecodeError, load
+
+        try:
+            return load(f)
+        except JSONDecodeError as e:
+            if self.wrap_errors:
+                if name := getattr(f, 'name', None):
+                    msg = f'json from file={name!r} - are you sure it contains properly formatted json?'
+                else:
+                    msg = "the provided json content - are you sure it's properly formatted json?"
+                raise InputValidationError(f'Unable to load {msg} - error: {e}') from e
+            else:
+                raise
 
 
 class Pickle(Serialized):

{cli_command_parser-2024.5.18.post1 → cli_command_parser-2024.5.31}/lib/cli_command_parser/inputs/numeric.py

@@ -13,6 +13,7 @@ from typing import Optional, Union
 from ..typing import NT, Bool, Number, NumType, RngType
 from .base import InputType
 from .exceptions import InputValidationError
+from .utils import RangeMixin, range_str
 
 __all__ = ['Range', 'NumRange']
 
@@ -102,7 +103,7 @@ class Range(NumericInput[NT]):
         raise InputValidationError(f'expected a value in the range {self._range_str()}')
 
 
-class NumRange(NumericInput[NT]):
+class NumRange(RangeMixin, NumericInput[NT]):
     """
     A range of integers or floats, optionally only bounded on one side.
 
@@ -122,10 +123,6 @@ class NumRange(NumericInput[NT]):
 
     __slots__ = ('type', 'snap', 'min', 'max', 'include_min', 'include_max')
     snap: bool
-    min: Number
-    max: Number
-    include_min: bool
-    include_max: bool
 
     def __init__(
         self,
@@ -170,17 +167,7 @@ class NumRange(NumericInput[NT]):
         return f'<{self.__class__.__name__}({self.type!r}, snap={self.snap!r})[{self._range_str()}]>'
 
     def _range_str(self, var: str = 'N') -> str:
-        if self.min is not None:
-            min_str = f'{self.min} {"<=" if self.include_min else "<"} '
-        else:
-            min_str = ''
-
-        if self.max is not None:
-            max_str = f' {"<=" if self.include_max else "<"} {self.max}'
-        else:
-            max_str = ''
-
-        return f'{min_str}{var}{max_str}'
+        return range_str(self.min, self.max, self.include_min, self.include_max, var)
 
     def handle_invalid(self, bound: Number, inclusive: bool, snap_dir: int) -> Number:
         """
@@ -199,11 +186,9 @@ class NumRange(NumericInput[NT]):
 
     def __call__(self, value: str) -> NT:
         value = self.type(value)
-        if self.min is not None:
-            # Bad if < when inclusive, bad if <= when exclusive
-            if (value < self.min) if self.include_min else (value <= self.min):
-                return self.handle_invalid(self.min, self.include_min, 1)
-        if self.max is not None:
-            if (value > self.max) if self.include_max else (value >= self.max):
-                return self.handle_invalid(self.max, self.include_max, -1)
-        return value
+        if self.value_lt_min(value):
+            return self.handle_invalid(self.min, self.include_min, 1)
+        elif self.value_gt_max(value):
+            return self.handle_invalid(self.max, self.include_max, -1)
+        else:
+            return value

{cli_command_parser-2024.5.18.post1 → cli_command_parser-2024.5.31}/lib/cli_command_parser/inputs/time.py

@@ -24,16 +24,17 @@ from locale import LC_ALL, setlocale
 from threading import RLock
 from typing import Collection, Iterator, Literal, Optional, Sequence, Type, TypeVar, Union, overload
 
-from ..typing import Bool, Locale, T, TimeBound
+from ..typing import Bool, Locale, Number, T, TimeBound
 from ..utils import MissingMixin
 from .base import InputType
 from .exceptions import InputValidationError, InvalidChoiceError
+from .utils import RangeMixin, range_str
 
 __all__ = ['DTFormatMode', 'Day', 'Month', 'TimeDelta', 'DateTime', 'Date', 'Time']
 
 DT = TypeVar('DT')
-TimeUnit = Literal['days', 'seconds', 'microseconds', 'milliseconds', 'minutes', 'hours', 'weeks']
-_TIMEDELTA_UNITS = {'days', 'seconds', 'microseconds', 'milliseconds', 'minutes', 'hours', 'weeks'}
+TimeUnit = Literal['microseconds', 'milliseconds', 'seconds', 'minutes', 'hours', 'days', 'weeks']
+_TIMEDELTA_UNITS = {'microseconds', 'milliseconds', 'seconds', 'minutes', 'hours', 'days', 'weeks'}
 DEFAULT_DATE_FMT = '%Y-%m-%d'
 DEFAULT_TIME_FMT = '%H:%M:%S'
 DEFAULT_DT_FMT = '%Y-%m-%d %H:%M:%S'
@@ -227,8 +228,8 @@ class Day(CalendarUnitInput, dt_type='day of the week'):
     _formats = {
         DTFormatMode.FULL: day_name,
         DTFormatMode.ABBREVIATION: day_abbr,
-        DTFormatMode.NUMERIC: range(7),
-        DTFormatMode.NUMERIC_ISO: range(1, 8),
+        DTFormatMode.NUMERIC: range(7),  # 0 = Monday; 6  = Sunday
+        DTFormatMode.NUMERIC_ISO: range(1, 8),  # 1 = Monday; 7 = Sunday
     }
 
     @overload
@@ -336,35 +337,62 @@ class Month(CalendarUnitInput, dt_type='month', min_index=1):
 # endregion
 
 
-class TimeDelta(InputType[timedelta]):
-    __slots__ = ('unit',)
+class TimeDelta(RangeMixin, InputType[timedelta]):
+    __slots__ = ('unit', 'min', 'max', 'include_min', 'include_max', 'int_only')
 
-    def __init__(self, unit: TimeUnit, fix_default: Bool = True):
+    def __init__(
+        self,
+        unit: TimeUnit,
+        *,
+        min: Number = None,  # noqa
+        max: Number = None,  # noqa
+        include_min: Bool = True,
+        include_max: Bool = False,
+        int_only: Bool = False,
+        fix_default: Bool = True,
+    ):
         unit = unit.lower()
         if unit not in _TIMEDELTA_UNITS:
             raise TypeError(f'Invalid {unit=} - expected one of: {", ".join(sorted(_TIMEDELTA_UNITS))}')
+        elif min is not None and max is not None and min >= max:
+            raise ValueError(f'Invalid {min=} >= {max=} - min must be less than max')
+
         super().__init__(fix_default)
         self.unit = unit
-        # TODO: min/max params like NumRange?
+        self.min = min
+        self.max = max
+        self.include_min = include_min
+        self.include_max = include_max
+        self.int_only = int_only
 
     def __call__(self, value: Union[str, int, float]) -> timedelta:
         if isinstance(value, str):
             try:
                 value = float(value.replace(',', '').replace('_', ''))  # allow comma or _ between thousands
             except ValueError as e:
-                raise InputValidationError(
-                    f'Invalid numeric {self.unit}={value!r} - expected an integer or float'
-                ) from e
+                exp_type = 'integer' if self.int_only else 'integer or float'
+                raise self._invalid(value, f'expected an {exp_type}') from e
+
+        if self.value_lt_min(value) or self.value_gt_max(value):
+            raise self._invalid(value, f'expected a value in the range {self._range_str()}')
+        elif self.int_only and int(value) != value:
+            raise self._invalid(value, f'expected an integer, not a {value.__class__.__name__}')
 
         return timedelta(**{self.unit: value})
 
+    def _invalid(self, value: Number, message: str) -> InputValidationError:
+        return InputValidationError(f'Invalid numeric {self.unit}={value!r} - {message}')
+
+    def _range_str(self) -> str:
+        return range_str(self.min, self.max, self.include_min, self.include_max, self.unit)
+
     def fix_default(self, value: Union[int, float, timedelta, None]) -> Optional[timedelta]:
         if value is None or isinstance(value, timedelta) or not self._fix_default:
             return value
         return self(value)
 
     def format_metavar(self, choice_delim: str = ',', sort_choices: bool = False) -> str:
-        return f'{{{self.unit}}}'
+        return f'{{{self._range_str()}}}'
 
 
 # region Date/Time Parse Inputs

{cli_command_parser-2024.5.18.post1 → cli_command_parser-2024.5.31}/lib/cli_command_parser/inputs/utils.py

@@ -10,17 +10,17 @@ import sys
 import warnings
 from contextlib import contextmanager
 from pathlib import Path
-from stat import S_IFMT, S_IFDIR, S_IFCHR, S_IFBLK, S_IFREG, S_IFIFO, S_IFLNK, S_IFSOCK
-from typing import TYPE_CHECKING, Union, Any, TextIO, BinaryIO, ContextManager
+from stat import S_IFBLK, S_IFCHR, S_IFDIR, S_IFIFO, S_IFLNK, S_IFMT, S_IFREG, S_IFSOCK
+from typing import TYPE_CHECKING, Any, BinaryIO, ContextManager, TextIO, Union
 from weakref import finalize
 
 from ..utils import FixedFlag
 from .exceptions import InputValidationError
 
 if TYPE_CHECKING:
-    from ..typing import Bool, FP, Converter
+    from ..typing import FP, Bool, Converter, Number
 
-__all__ = ['InputParam', 'StatMode', 'FileWrapper', 'fix_windows_path']
+__all__ = ['InputParam', 'StatMode', 'FileWrapper', 'fix_windows_path', 'range_str', 'RangeMixin']
 
 
 class InputParam:
@@ -214,3 +214,36 @@ def fix_windows_path(path: Path) -> Path:
         return alt_path
     else:
         return path
+
+
+def range_str(min_val: Number, max_val: Number, include_min: Bool, include_max: Bool, var: str = 'N') -> str:
+    if min_val is not None:
+        min_str = f'{min_val} {"<=" if include_min else "<"} '
+    else:
+        min_str = ''
+
+    if max_val is not None:
+        max_str = f' {"<=" if include_max else "<"} {max_val}'
+    else:
+        max_str = ''
+
+    return f'{min_str}{var}{max_str}'
+
+
+class RangeMixin:
+    __slots__ = ()  # It isn't possible to use 2+ bases when they both have content in __slots__
+    min: Number
+    max: Number
+    include_min: bool
+    include_max: bool
+
+    def value_lt_min(self, value: Number) -> bool:
+        if self.min is not None:
+            # Bad if < when inclusive, bad if <= when exclusive
+            return (value < self.min) if self.include_min else (value <= self.min)
+        return False
+
+    def value_gt_max(self, value: Number) -> bool:
+        if self.max is not None:
+            return (value > self.max) if self.include_max else (value >= self.max)
+        return False

{cli_command_parser-2024.5.18.post1 → cli_command_parser-2024.5.31}/lib/cli_command_parser/parameters/choice_map.py

@@ -9,7 +9,7 @@ from __future__ import annotations
 from functools import partial
 from string import printable, whitespace
 from types import MethodType
-from typing import Callable, Collection, Generic, Mapping, NoReturn, Optional, Type, TypeVar, Union
+from typing import TYPE_CHECKING, Callable, Collection, Generic, Mapping, NoReturn, Optional, Type, TypeVar, Union
 
 from ..context import ctx
 from ..exceptions import BadArgument, CommandDefinitionError, InvalidChoice, ParameterDefinitionError
@@ -20,6 +20,9 @@ from ..utils import _NotSet, camel_to_snake_case, short_repr
 from .actions import Concatenate
 from .base import BasePositional
 
+if TYPE_CHECKING:
+    from ..metadata import ProgramMetadata
+
 __all__ = ['SubCommand', 'Action', 'Choice', 'ChoiceMap']
 
 T = TypeVar('T')
@@ -247,6 +250,13 @@ class SubCommand(ChoiceMap[CommandCls], title='Subcommands', choice_validation_e
         else:
             self._validate_positional(choice)
 
+        if help is None:
+            # This approach was used because importing get_metadata from core would result in a circular dependency
+            meta: ProgramMetadata = command.__class__.meta(command)
+            # print(f'Registering {choice=} -> {command=} w/ {meta.description=}, {meta.parent=}')
+            if meta.description and (not meta.parent or meta.parent.description != meta.description):
+                help = meta.description  # noqa
+
         try:
             self.register_choice(choice, command, help)
         except CommandDefinitionError:

{cli_command_parser-2024.5.18.post1 → cli_command_parser-2024.5.31/lib/cli_command_parser.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: cli_command_parser
-Version: 2024.5.18.post1
+Version: 2024.5.31
 Summary: CLI Command Parser
 Home-page: https://github.com/dskrypa/cli_command_parser
 Author: Doug Skrypa