Add 'argtypes.py', with useful argument types for users

- integer: like 'int', but accepts arbitrary bases (i.e. 0x10), and optional
  suffix like "10K" or "64Mi"
- hexadecimal: base 16 integer, with nicer error text than using a lambda
- Range: integer from specified range, when that may be too large for 'choices'
- IntSet: set of integers from specified range

Author: BillTompkins

cmd2/argtypes.py

@@ -0,0 +1,113 @@
+"""Useful argument types."""
+
+from collections.abc import Iterable
+
+_int_suffixes = {
+    # SI number suffixes (unit prefixes):
+    "K": 1_000,
+    "M": 1_000_000,
+    "G": 1_000_000_000,
+    "T": 1_000_000_000_000,
+    "P": 1_000_000_000_000_000,
+    # IEC number suffixes (unit prefixes):
+    "Ki": 1024,
+    "Mi": 1024 * 1024,
+    "Gi": 1024 * 1024 * 1024,
+    "Ti": 1024 * 1024 * 1024 * 1024,
+    "Pi": 1024 * 1024 * 1024 * 1024 * 1024,
+}
+
+
+def integer(value_str: str) -> int:
+    """Will accept any base, and optional suffix like '64K'."""
+    multiplier = 1
+    # If there is a matching suffix, use its multiplier:
+    for suffix, suffix_multiplier in _int_suffixes.items():
+        if value_str.endswith(suffix):
+            value_str = value_str.removesuffix(suffix)
+            multiplier = suffix_multiplier
+            break
+
+    return int(value_str, 0) * multiplier
+
+
+def hexadecimal(value_str: str) -> int:
+    """Parse hexidecimal integer, with optional '0x' prefix."""
+    return int(value_str, base=16)
+
+
+class Range:
+    """Useful as type for large ranges, when 'choices=range(maxval)' would be excessively large."""
+
+    def __init__(self, firstval: int, secondval: int | None = None) -> None:
+        """Construct a Range, with same syntax as 'range'.
+
+        :param firstval: either the top end of range (if 'secondval' is missing), or the bottom end
+        :param secondval: top end of range (one higher than maximum value)
+        """
+        if secondval is None:
+            self.bottom = 0
+            self.top = firstval
+        else:
+            self.bottom = firstval
+            self.top = secondval
+
+        self.range_str = f"[{self.bottom}..{self.top - 1}]"
+
+    def __repr__(self) -> str:
+        """Will be printed as the 'argument type' to user on syntax or range error."""
+        return f"Range{self.range_str}"
+
+    def __call__(self, arg: str) -> int:
+        """Parse the string argument and checks validity."""
+        val = integer(arg)
+        if self.bottom <= val < self.top:
+            return val
+        raise ValueError(f"Value '{val}' not within {self.range_str}")
+
+
+class IntSet:
+    """Set of integers from a specified range.
+
+    e.g. '5', '1-3,8', 'all'
+    """
+
+    def __init__(self, firstval: int, secondval: int | None = None) -> None:
+        """Construct an IntSet, with same syntax as 'range'.
+
+        :param firstval: either the top end of range (if 'secondval' is missing), or the bottom end
+        :param secondval: top end of range (one higher than maximum value)
+        """
+        if secondval is None:
+            self.bottom = 0
+            self.top = firstval
+        else:
+            self.bottom = firstval
+            self.top = secondval
+
+        self.range_str = f"[{self.bottom}..{self.top - 1}]"
+
+    def __repr__(self) -> str:
+        """Will be printed as the 'argument type' to user on syntax or range error."""
+        return f"IntSet{self.range_str}"
+
+    def __call__(self, arg: str) -> Iterable:
+        """Parse a string into an iterable returning ints."""
+        if arg == 'all':
+            return range(self.bottom, self.top)
+
+        out = []
+        for piece in arg.split(','):
+            if '-' in piece:
+                a, b = [int(x) for x in piece.split('-', 2)]
+                if a < self.bottom:
+                    raise ValueError(f"Value '{a}' not within {self.range_str}")
+                if b >= self.top:
+                    raise ValueError(f"Value '{b}' not within {self.range_str}")
+                out += list(range(a, b + 1))
+            else:
+                val = int(piece)
+                if not self.bottom <= val < self.top:
+                    raise ValueError(f"Value '{val}' not within {self.range_str}")
+                out += [val]
+        return out

tests/test_argtypes.py

@@ -0,0 +1,129 @@
+"""Tests of additional argument types"""
+
+import argparse
+
+import pytest
+
+import cmd2
+from cmd2.argtypes import IntSet, Range, hexadecimal, integer
+
+from .conftest import (
+    run_cmd,
+)
+
+
+class CustomTypesApp(cmd2.Cmd):
+    def __init__(self) -> None:
+        cmd2.Cmd.__init__(self)
+
+    def namespace_provider(self) -> argparse.Namespace:
+        ns = argparse.Namespace()
+        ns.custom_stuff = "custom"
+        return ns
+
+    @staticmethod
+    def _test_parser_builder() -> cmd2.Cmd2ArgumentParser:
+        test_parser = cmd2.Cmd2ArgumentParser()
+        test_parser.add_argument('--int', dest='intarg', type=integer, help='IntegerHelp')
+        test_parser.add_argument('--hex', dest='hexarg', type=hexadecimal, help='HexHelp')
+        test_parser.add_argument('--range', dest='rangearg', type=Range(10), help='RangeHelp')
+        test_parser.add_argument('--set', dest='setarg', type=IntSet(5), help='SetHelp')
+        test_parser.add_argument('--highset', dest='setarg', type=IntSet(5, 10), help='SetHelp')
+        return test_parser
+
+    @cmd2.with_argparser(_test_parser_builder)
+    def do_test(self, args, *, keyword_arg: str | None = None) -> None:
+        """Test custom types
+        :param args: argparse namespace
+        :param keyword_arg: Optional keyword arguments
+        """
+        if args.intarg is not None:
+            self.stdout.write(f"Integer {args.intarg}")
+        if args.hexarg is not None:
+            print(f"Hex {args.hexarg}")
+        if args.rangearg is not None:
+            print(f"Range {args.rangearg}")
+        if args.setarg is not None:
+            print(f"Set {list(args.setarg)}")
+
+
+@pytest.fixture
+def custom_types_app():
+    return CustomTypesApp()
+
+
+def test_int_basic(custom_types_app) -> None:
+    out, _err = run_cmd(custom_types_app, 'test --int 5')
+    assert out == ['Integer 5']
+
+
+def test_int_hex(custom_types_app) -> None:
+    out, _err = run_cmd(custom_types_app, 'test --int 0xf')
+    assert out == ['Integer 15']
+
+
+def test_int_bin(custom_types_app) -> None:
+    out, _err = run_cmd(custom_types_app, 'test --int 0b1000_0000')
+    assert out == ['Integer 128']
+
+
+def test_int_si_suffix(custom_types_app) -> None:
+    out, _err = run_cmd(custom_types_app, 'test --int 5M')
+    assert out == ['Integer 5000000']
+
+
+def test_int_iec_suffix(custom_types_app) -> None:
+    out, _err = run_cmd(custom_types_app, 'test --int 10Ki')
+    assert out == ['Integer 10240']
+
+
+def test_int_failure(custom_types_app) -> None:
+    _out, err = run_cmd(custom_types_app, 'test --int 5bob')
+    assert err[-1:] == ["Error: argument --int: invalid integer value: '5bob'"]
+
+
+def test_hex_basic(custom_types_app) -> None:
+    out, _err = run_cmd(custom_types_app, 'test --hex 10')
+    assert out == ['Hex 16']
+
+
+def test_hex_prefixed(custom_types_app) -> None:
+    out, _err = run_cmd(custom_types_app, 'test --hex 0x10')
+    assert out == ['Hex 16']
+
+
+def test_hex_failure(custom_types_app) -> None:
+    _out, err = run_cmd(custom_types_app, 'test --hex 5bob')
+    assert err[-1:] == ["Error: argument --hex: invalid hexadecimal value: '5bob'"]
+
+
+def test_range(custom_types_app) -> None:
+    out, _err = run_cmd(custom_types_app, 'test --range 4')
+    assert out == ['Range 4']
+
+
+def test_range_outside(custom_types_app) -> None:
+    _out, err = run_cmd(custom_types_app, 'test --range 10')
+    assert err[-1:] == ["Error: argument --range: invalid Range[0..9] value: '10'"]
+
+
+def test_intset_single(custom_types_app) -> None:
+    out, _err = run_cmd(custom_types_app, 'test --set 4')
+    assert out == ['Set [4]']
+
+
+def test_intset_single_out_of_range(custom_types_app) -> None:
+    _out, err = run_cmd(custom_types_app, 'test --set 5')
+    assert err[-1:] == ["Error: argument --set: invalid IntSet[0..4] value: '5'"]
+
+
+def test_intset_high_multi(custom_types_app) -> None:
+    out, _err = run_cmd(custom_types_app, 'test --highset 5,7-9')
+    print(_err)
+    print(out)
+    assert out == ['Set [5, 7, 8, 9]']
+
+
+def test_intset_high_all(custom_types_app) -> None:
+    out, _err = run_cmd(custom_types_app, 'test --highset all')
+    assert out == ['Set [5, 6, 7, 8, 9]']