edq-utils 0.0.3__tar.gz → 0.0.4__tar.gz

{edq_utils-0.0.3/edq_utils.egg-info → edq_utils-0.0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edq-utils
-Version: 0.0.3
+Version: 0.0.4
 Summary: Common utilities used by EduLinq Python projects.
 Author-email: Eriq Augustine <eriq@edulinq.org>
 License: MIT License

{edq_utils-0.0.3 → edq_utils-0.0.4}/edq/__init__.py

@@ -2,4 +2,4 @@
 General Python tools used by several EduLinq projects.
 """
 
-__version__ = '0.0.3'
+__version__ = '0.0.4'

edq_utils-0.0.4/edq/cli/testing/cli-test.py

@@ -0,0 +1,42 @@
+#  # pylint: disable=invalid-name
+
+"""
+Run specified CLI test files.
+"""
+
+import argparse
+import sys
+import unittest
+
+import edq.core.argparser
+import edq.testing.cli
+import edq.testing.cli_test
+
+def run_cli(args: argparse.Namespace) -> int:
+    """ Run the CLI. """
+
+    edq.testing.cli.add_test_paths(edq.testing.cli_test.CLITest, args.paths)
+
+    runner = unittest.TextTestRunner(verbosity = 2)
+    tests = unittest.defaultTestLoader.loadTestsFromTestCase(edq.testing.cli_test.CLITest)
+    results = runner.run(tests)
+
+    return len(results.errors) + len(results.failures)
+
+def main() -> int:
+    """ Get a parser, parse the args, and call run. """
+    return run_cli(_get_parser().parse_args())
+
+def _get_parser() -> edq.core.argparser.Parser:
+    """ Get the parser. """
+
+    parser = edq.core.argparser.get_default_parser(__doc__.strip())
+
+    parser.add_argument('paths', metavar = 'PATH',
+        type = str, nargs = '+',
+        help = 'Path to CLI test case files.')
+
+    return parser
+
+if (__name__ == '__main__'):
+    sys.exit(main())

edq_utils-0.0.4/edq/cli/version.py

@@ -0,0 +1,27 @@
+"""
+Get the version of the EduLinq Python utils package.
+"""
+
+import argparse
+import sys
+
+import edq.core.argparser
+import edq.core.version
+
+def run_cli(args: argparse.Namespace) -> int:
+    """ Run the CLI. """
+
+    print(f"v{edq.core.version.get_version()}")
+    return 0
+
+def main() -> int:
+    """ Get a parser, parse the args, and call run. """
+    return run_cli(_get_parser().parse_args())
+
+def _get_parser() -> edq.core.argparser.Parser:
+    """ Get the parser. """
+
+    return edq.core.argparser.get_default_parser(__doc__.strip())
+
+if (__name__ == '__main__'):
+    sys.exit(main())

edq_utils-0.0.4/edq/core/argparser.py

@@ -0,0 +1,112 @@
+"""
+A place to handle common CLI arguments.
+"parsers" in this file are always assumed to be argparse parsers.
+
+The general idea is that callers can register callbacks to be called before and after parsing CLI arguments.
+Pre-callbacks are generally intended to add arguments to the parser,
+while post-callbacks are generally intended to act on the results of parsing.
+"""
+
+import argparse
+import typing
+
+import edq.core.log
+
+@typing.runtime_checkable
+class PreParseFunction(typing.Protocol):
+    """
+    A function that can be called before parsing arguments.
+    """
+
+    def __call__(self, parser: argparse.ArgumentParser, extra_state: typing.Dict[str, typing.Any]) -> None:
+        """
+        Prepare a parser for parsing.
+        This is generally used for adding your module's arguments to the parser,
+        for example a logging module may add arguments to set a logging level.
+
+        The extra state is shared between all pre-parse functions
+        and will be placed in the final parsed output under `_pre_extra_state_`.
+        """
+
+@typing.runtime_checkable
+class PostParseFunction(typing.Protocol):
+    """
+    A function that can be called after parsing arguments.
+    """
+
+    def __call__(self,
+            parser: argparse.ArgumentParser,
+            args: argparse.Namespace,
+            extra_state: typing.Dict[str, typing.Any]) -> None:
+        """
+        Take actions after arguments are parsed.
+        This is generally used for initializing your module with options,
+        for example a logging module may set a logging level.
+
+        The extra state is shared between all post-parse functions
+        and will be placed in the final parsed output under `_post_extra_state_`.
+        """
+
+class Parser(argparse.ArgumentParser):
+    """
+    Extend an argparse parser to call the pre and post functions.
+    """
+
+    def __init__(self, *args: typing.Any, **kwargs: typing.Any) -> None:
+        super().__init__(*args, **kwargs)
+
+        self._pre_parse_callbacks: typing.Dict[str, PreParseFunction] = {}
+        self._post_parse_callbacks: typing.Dict[str, PostParseFunction] = {}
+
+    def register_callbacks(self,
+            key: str,
+            pre_parse_callback: typing.Union[PreParseFunction, None] = None,
+            post_parse_callback: typing.Union[PostParseFunction, None] = None,
+            ) -> None:
+        """
+        Register callback functions to run before/after argument parsing.
+        Any existing callbacks under the specified key will be replaced.
+        """
+
+        if (pre_parse_callback is not None):
+            self._pre_parse_callbacks[key] = pre_parse_callback
+
+        if (post_parse_callback is not None):
+            self._post_parse_callbacks[key] = post_parse_callback
+
+    def parse_args(self,  # type: ignore[override]
+            *args: typing.Any,
+            skip_keys: typing.Union[typing.List[str], None] = None,
+            **kwargs: typing.Any) -> argparse.Namespace:
+        if (skip_keys is None):
+            skip_keys = []
+
+        # Call pre-parse callbacks.
+        pre_extra_state: typing.Dict[str, typing.Any] = {}
+        for (key, pre_parse_callback) in self._pre_parse_callbacks.items():
+            if (key not in skip_keys):
+                pre_parse_callback(self, pre_extra_state)
+
+        # Parse the args.
+        parsed_args = super().parse_args(*args, **kwargs)
+
+        # Call post-parse callbacks.
+        post_extra_state: typing.Dict[str, typing.Any] = {}
+        for (key, post_parse_callback) in self._post_parse_callbacks.items():
+            if (key not in skip_keys):
+                post_parse_callback(self, parsed_args, post_extra_state)
+
+        # Attach the additional state to the args.
+        setattr(parsed_args, '_pre_extra_state_', pre_extra_state)
+        setattr(parsed_args, '_post_extra_state_', post_extra_state)
+
+        return parsed_args  # type: ignore[no-any-return]
+
+def get_default_parser(description: str) -> Parser:
+    """ Get a parser with the default callbacks already attached. """
+
+    parser = Parser(description = description)
+
+    parser.register_callbacks('log', edq.core.log.set_cli_args, edq.core.log.init_from_args)
+
+    return parser

edq_utils-0.0.4/edq/core/argparser_test.py

@@ -0,0 +1,124 @@
+import functools
+
+import edq.core.argparser
+import edq.testing.unittest
+
+class TestArgParser(edq.testing.unittest.BaseTest):
+    """ Test argument parsing. """
+
+    def test_callbacks_base(self):
+        """ Test the argument parsing callbacks. """
+
+        # [(parse text, [(key, pre, post), ...], skip keys, expected (as dict)), ...]
+        test_cases = [
+            # Empty
+            (
+                "",
+                [],
+                [],
+                {
+                    '_pre_extra_state_': {},
+                    '_post_extra_state_': {},
+                },
+            ),
+
+            # Single Callbacks
+            (
+                "",
+                [
+                    ('test', functools.partial(_pre_callback_append, value = 1), functools.partial(_post_callback_append, value = 2)),
+                ],
+                [],
+                {
+                    '_pre_extra_state_': {
+                        'append': [1],
+                    },
+                    '_post_extra_state_': {
+                        'append': [2],
+                    },
+                },
+            ),
+
+            # Double Callbacks
+            (
+                "",
+                [
+                    ('test1', functools.partial(_pre_callback_append, value = 1), functools.partial(_post_callback_append, value = 2)),
+                    ('test2', functools.partial(_pre_callback_append, value = 3), functools.partial(_post_callback_append, value = 4)),
+                ],
+                [],
+                {
+                    '_pre_extra_state_': {
+                        'append': [1, 3],
+                    },
+                    '_post_extra_state_': {
+                        'append': [2, 4],
+                    },
+                },
+            ),
+
+            # Split Callbacks
+            (
+                "",
+                [
+                    ('test1', functools.partial(_pre_callback_append, value = 1), None),
+                    ('test2', None, functools.partial(_post_callback_append, value = 4)),
+                ],
+                [],
+                {
+                    '_pre_extra_state_': {
+                        'append': [1],
+                    },
+                    '_post_extra_state_': {
+                        'append': [4],
+                    },
+                },
+            ),
+
+            # Override Callbacks
+            (
+                "",
+                [
+                    ('test', functools.partial(_pre_callback_append, value = 1), functools.partial(_post_callback_append, value = 2)),
+                    ('test', functools.partial(_pre_callback_append, value = 3), functools.partial(_post_callback_append, value = 4)),
+                ],
+                [],
+                {
+                    '_pre_extra_state_': {
+                        'append': [3],
+                    },
+                    '_post_extra_state_': {
+                        'append': [4],
+                    },
+                },
+            ),
+        ]
+
+        for (i, test_case) in enumerate(test_cases):
+            (text, registrations, skip_keys, expected) = test_case
+
+            with self.subTest(msg = f"Case {i} ('{text}'):"):
+                parser = edq.core.argparser.Parser(f"Case {i}")
+                for (key, pre, post) in registrations:
+                    parser.register_callbacks(key, pre, post)
+
+                args = parser.parse_args(text.split(), skip_keys = skip_keys)
+
+                actual = vars(args)
+                self.assertJSONDictEqual(expected, actual)
+
+def _pre_callback_append(parser, extra_state, key = 'append', value = None) -> None:
+    """ Append the given value into the extra state. """
+
+    if (key not in extra_state):
+        extra_state[key] = []
+
+    extra_state[key].append(value)
+
+def _post_callback_append(parser, args, extra_state, key = 'append', value = None) -> None:
+    """ Append the given value into the extra state. """
+
+    if (key not in extra_state):
+        extra_state[key] = []
+
+    extra_state[key].append(value)

edq_utils-0.0.4/edq/core/log.py

@@ -0,0 +1,101 @@
+import argparse
+import logging
+import typing
+
+DEFAULT_LOGGING_LEVEL: str = logging.getLevelName(logging.INFO)
+DEFAULT_LOGGING_FORMAT: str = '%(asctime)s [%(levelname)-8s] - %(filename)s:%(lineno)s -- %(message)s'
+
+LEVELS: typing.List[str] = [
+    'TRACE',
+    logging.getLevelName(logging.DEBUG),
+    logging.getLevelName(logging.INFO),
+    logging.getLevelName(logging.WARNING),
+    logging.getLevelName(logging.ERROR),
+    logging.getLevelName(logging.CRITICAL),
+]
+
+def init(level: str = DEFAULT_LOGGING_LEVEL, log_format: str = DEFAULT_LOGGING_FORMAT,
+        warn_loggers: typing.Union[typing.List[str], None] = None,
+        **kwargs: typing.Any) -> None:
+    """
+    Initialize or re-initialize the logging infrastructure.
+    The list of warning loggers is a list of identifiers for loggers (usually third-party) to move up to warning on init.
+    """
+
+    # Add trace.
+    _add_logging_level('TRACE', logging.DEBUG - 5)
+
+    logging.basicConfig(level = level, format = log_format, force = True)
+
+    if (warn_loggers is not None):
+        for warn_logger in warn_loggers:
+            logging.getLogger(warn_logger).setLevel(logging.WARNING)
+
+    logging.trace("Logging initialized with level '%s'.", level)  # type: ignore[attr-defined]
+
+def set_cli_args(parser: argparse.ArgumentParser, extra_state: typing.Dict[str, typing.Any]) -> None:
+    """
+    Set common CLI arguments.
+    This is a sibling to init_from_args(), as the arguments set here can be interpreted there.
+    """
+
+    parser.add_argument('--log-level', dest = 'log_level',
+            action = 'store', type = str, default = logging.getLevelName(logging.INFO),
+            choices = LEVELS,
+            help = 'Set the logging level (default: %(default)s).')
+
+    parser.add_argument('--quiet', dest = 'quiet',
+            action = 'store_true', default = False,
+            help = 'Set the logging level to warning (overrides --log-level) (default: %(default)s).')
+
+    parser.add_argument('--debug', dest = 'debug',
+            action = 'store_true', default = False,
+            help = 'Set the logging level to debug (overrides --log-level and --quiet) (default: %(default)s).')
+
+def init_from_args(
+        parser: argparse.ArgumentParser,
+        args: argparse.Namespace,
+        extra_state: typing.Dict[str, typing.Any]) -> None:
+    """
+    Take in args from a parser that was passed to set_cli_args(),
+    and call init() with the appropriate arguments.
+    """
+
+    level = args.log_level
+
+    if (args.quiet):
+        level = logging.getLevelName(logging.WARNING)
+
+    if (args.debug):
+        level = logging.getLevelName(logging.DEBUG)
+
+    init(level)
+
+def _add_logging_level(level_name: str, level_number: int, method_name: typing.Union[str, None] = None) -> None:
+    """
+    Add a new logging level.
+
+    See https://stackoverflow.com/questions/2183233/how-to-add-a-custom-loglevel-to-pythons-logging-facility/35804945#35804945 .
+    """
+
+    if (method_name is None):
+        method_name = level_name.lower()
+
+    # Level has already been defined.
+    if hasattr(logging, level_name):
+        return
+
+    def log_for_level(self: typing.Any, message: str, *args: typing.Any, **kwargs: typing.Any) -> None:
+        if self.isEnabledFor(level_number):
+            self._log(level_number, message, args, **kwargs)
+
+    def log_to_root(message: str, *args: typing.Any, **kwargs: typing.Any) -> None:
+        logging.log(level_number, message, *args, **kwargs)
+
+    logging.addLevelName(level_number, level_name)
+    setattr(logging, level_name, level_number)
+    setattr(logging.getLoggerClass(), method_name, log_for_level)
+    setattr(logging, method_name, log_to_root)
+
+# Load the default logging when this module is loaded.
+init()

edq_utils-0.0.4/edq/core/version.py

@@ -0,0 +1,6 @@
+import edq
+
+def get_version() -> str:
+    """ Get the version for the EduLinq Python utils. """
+
+    return edq.__version__

edq_utils-0.0.4/edq/testing/asserts.py

@@ -0,0 +1,66 @@
+"""
+More complex testing assertions.
+Often used as output checks in CLI tests.
+"""
+
+import re
+import typing
+
+import edq.testing.unittest
+
+TRACEBACK_LINE_REGEX: str = r'^\s*File "[^"]+", line \d+,.*$\n.*$(\n\s*[\^~]+\s*$)?'
+TRACEBACK_LINE_REPLACEMENT: str = '<TRACEBACK_LINE>'
+
+TEXT_NORMALIZATIONS: typing.List[typing.Tuple[str, str]] = [
+    (r'^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2},\d+ \[\S+ *\] - .*\.py:\d+ -- ', '<LOG_PREFIX> -- '),
+    (r'\d+\.\d+ seconds', '<DURATION_SECONDS>'),
+    (r'\bv\d+\.\d+\.\d+\b', '<VERSION>'),
+    (r'^\s*File "[^"]+", line \d+,.*$\n.*$(\n\s*[\^~]+\s*$)?', '<TRACEBACK_LINE>'),
+    (rf'{TRACEBACK_LINE_REPLACEMENT}(\n{TRACEBACK_LINE_REPLACEMENT})*', '<TRACEBACK>'),
+]
+"""
+Normalization to make to the CLI output.
+Formatted as: [(regex, replacement), ...]
+"""
+
+@typing.runtime_checkable
+class StringComparisonAssertion(typing.Protocol):
+    """
+    A function that can be used as a comparison assertion for a test.
+    """
+
+    def __call__(self,
+            test: edq.testing.unittest.BaseTest,
+            expected: str, actual: str,
+            **kwargs: typing.Any) -> None:
+        """
+        Perform an assertion between expected and actual data.
+        """
+
+
+def content_equals_raw(test: edq.testing.unittest.BaseTest, expected: str, actual: str, **kwargs: typing.Any) -> None:
+    """ Check for equality using a simple string comparison. """
+
+    test.assertEqual(expected, actual)
+
+def content_equals_normalize(test: edq.testing.unittest.BaseTest, expected: str, actual: str, **kwargs: typing.Any) -> None:
+    """
+    Perform some standard text normalizations (see TEXT_NORMALIZATIONS) before using simple string comparison.
+    """
+
+    for (regex, replacement) in TEXT_NORMALIZATIONS:
+        expected = re.sub(regex, replacement, expected, flags = re.MULTILINE)
+        actual = re.sub(regex, replacement, actual, flags = re.MULTILINE)
+
+    content_equals_raw(test, expected, actual)
+
+def has_content_100(test: edq.testing.unittest.BaseTest, expected: str, actual: str, **kwargs: typing.Any) -> None:
+    """ Check the that output has at least 100 characters. """
+
+    return has_content(test, expected, actual, min_length = 100)
+
+def has_content(test: edq.testing.unittest.BaseTest, expected: str, actual: str, min_length: int = 100) -> None:
+    """ Ensure that the output has content of at least some length. """
+
+    message = f"Output does not meet minimum length of {min_length}, it is only {len(actual)}."
+    test.assertTrue((len(actual) >= min_length), msg = message)

edq_utils-0.0.4/edq/testing/cli.py

@@ -0,0 +1,253 @@
+"""
+Infrastructure for testing CLI tools using a JSON file which describes a test case,
+which is essentially an invocation of a CLI tool and the expected output.
+
+The test case file must be a `.txt` file that live in TEST_CASES_DIR.
+The file contains two parts (separated by a line with just TEST_CASE_SEP):
+the first part which is a JSON object (see below for available keys),
+and a second part which is the expected text output (stdout).
+For the keys of the JSON section, see the defaulted arguments to CLITestInfo.
+The options JSON will be splatted into CLITestInfo's constructor.
+
+The expected output or any argument can reference the test's current temp or data dirs with `__TEMP_DIR__()` or `__DATA_DIR__()`, respectively.
+An optional slash-separated path can be used as an argument to reference a path within those base directories.
+For example, `__DATA_DIR__(foo/bar.txt)` references `bar.txt` inside the `foo` directory inside the data directory.
+"""
+
+import contextlib
+import glob
+import io
+import os
+import re
+import sys
+import typing
+
+import edq.testing.asserts
+import edq.testing.unittest
+import edq.util.dirent
+import edq.util.json
+import edq.util.pyimport
+
+THIS_DIR: str = os.path.abspath(os.path.dirname(os.path.realpath(__file__)))
+BASE_TESTDATA_DIR: str = os.path.join(THIS_DIR, "testdata", "cli")
+TEST_CASES_DIR: str = os.path.join(BASE_TESTDATA_DIR, "tests")
+DATA_DIR: str = os.path.join(BASE_TESTDATA_DIR, "data")
+
+TEST_CASE_SEP: str = '---'
+DATA_DIR_ID: str = '__DATA_DIR__'
+TEMP_DIR_ID: str = '__TEMP_DIR__'
+REL_DIR_ID: str = '__REL_DIR__'
+
+DEFAULT_ASSERTION_FUNC_NAME: str = 'edq.testing.asserts.content_equals_normalize'
+
+BASE_TEMP_DIR_ATTR: str = '_edq_cli_base_test_dir'
+
+class CLITestInfo:
+    """ The required information to run a CLI test. """
+
+    def __init__(self,
+            test_name: str,
+            base_dir: str,
+            temp_dir: str,
+            cli: typing.Union[str, None] = None,
+            arguments: typing.Union[typing.List[str], None] = None,
+            error: bool = False,
+            platform_skip: typing.Union[str, None] = None,
+            stdout_assertion_func: typing.Union[str, None] = DEFAULT_ASSERTION_FUNC_NAME,
+            stderr_assertion_func: typing.Union[str, None] = None,
+            expected_stdout: str = '',
+            expected_stderr: str = '',
+            strip_error_output: bool = True,
+            **kwargs: typing.Any) -> None:
+        self.test_name: str = test_name
+        """ The name of this test. """
+
+        self.base_dir: str = base_dir
+        """ The base directory for this test (usually the dir the CLI test file lives. """
+
+        self.temp_dir: str = temp_dir
+        """ A temp directory that this test has access to. """
+
+        edq.util.dirent.mkdir(temp_dir)
+
+        if (cli is None):
+            raise ValueError("Missing CLI module.")
+
+        self.module_name: str = cli
+        """ The name of the module to invoke. """
+
+        self.module: typing.Any = edq.util.pyimport.import_name(self.module_name)
+        """ The module to invoke. """
+
+        if (arguments is None):
+            arguments = []
+
+        self.arguments: typing.List[str] = arguments
+        """ The CLI arguments. """
+
+        self.error: bool = error
+        """ Whether or not this test is expected to be an error (raise an exception). """
+
+        self.platform_skip: typing.Union[str, None] = platform_skip
+        """ If the current platform matches this regular expression, then the test will be skipped. """
+
+        self.stdout_assertion_func: typing.Union[edq.testing.asserts.StringComparisonAssertion, None] = None
+        """ The assertion func to compare the expected and actual stdout of the CLI. """
+
+        if (stdout_assertion_func is not None):
+            self.stdout_assertion_func = edq.util.pyimport.fetch(stdout_assertion_func)
+
+        self.stderr_assertion_func: typing.Union[edq.testing.asserts.StringComparisonAssertion, None] = None
+        """ The assertion func to compare the expected and actual stderr of the CLI. """
+
+        if (stderr_assertion_func is not None):
+            self.stderr_assertion_func = edq.util.pyimport.fetch(stderr_assertion_func)
+
+        self.expected_stdout: str = expected_stdout
+        """ The expected stdout. """
+
+        self.expected_stderr: str = expected_stderr
+        """ The expected stderr. """
+
+        if (error and strip_error_output):
+            self.expected_stdout = self.expected_stdout.strip()
+            self.expected_stderr = self.expected_stderr.strip()
+
+        # Make any path normalizations over the arguments and expected output.
+        self.expected_stdout = self._expand_paths(self.expected_stdout)
+        self.expected_stderr = self._expand_paths(self.expected_stderr)
+        for (i, argument) in enumerate(self.arguments):
+            self.arguments[i] = self._expand_paths(argument)
+
+    def _expand_paths(self, text: str) -> str:
+        """
+        Expand path replacements in testing text.
+        This allows for consistent paths (even absolute paths) in the test text.
+        """
+
+        replacements = [
+            (DATA_DIR_ID, DATA_DIR),
+            (TEMP_DIR_ID, self.temp_dir),
+            (REL_DIR_ID, self.base_dir),
+        ]
+
+        for (key, target_dir) in replacements:
+            text = replace_path_pattern(text, key, target_dir)
+
+        return text
+
+    @staticmethod
+    def load_path(path: str, test_name: str, base_temp_dir: str) -> 'CLITestInfo':
+        """ Load a CLI test file and extract the test info. """
+
+        options, expected_stdout = read_test_file(path)
+
+        options['expected_stdout'] = expected_stdout
+
+        base_dir = os.path.dirname(os.path.abspath(path))
+        temp_dir = os.path.join(base_temp_dir, test_name)
+
+        return CLITestInfo(test_name, base_dir, temp_dir, **options)
+
+def read_test_file(path: str) -> typing.Tuple[typing.Dict[str, typing.Any], str]:
+    """ Read a test case file and split the output into JSON data and text. """
+
+    json_lines: typing.List[str] = []
+    output_lines: typing.List[str] = []
+
+    text = edq.util.dirent.read_file(path, strip = False)
+
+    accumulator = json_lines
+    for line in text.split("\n"):
+        if (line.strip() == TEST_CASE_SEP):
+            accumulator = output_lines
+            continue
+
+        accumulator.append(line)
+
+    options = edq.util.json.loads(''.join(json_lines))
+    output = "\n".join(output_lines)
+
+    return options, output
+
+def replace_path_pattern(text: str, key: str, target_dir: str) -> str:
+    """ Make any test replacement inside the given string. """
+
+    match = re.search(rf'{key}\(([^)]*)\)', text)
+    if (match is not None):
+        filename = match.group(1)
+
+        # Normalize any path separators.
+        filename = os.path.join(*filename.split('/'))
+
+        if (filename == ''):
+            path = target_dir
+        else:
+            path = os.path.join(target_dir, filename)
+
+        text = text.replace(match.group(0), path)
+
+    return text
+
+def _get_test_method(test_name: str, path: str) -> typing.Callable:
+    """ Get a test method that represents the test case at the given path. """
+
+    def __method(self: edq.testing.unittest.BaseTest) -> None:
+        test_info = CLITestInfo.load_path(path, test_name, getattr(self, BASE_TEMP_DIR_ATTR))
+
+        if ((test_info.platform_skip is not None) and re.search(test_info.platform_skip, sys.platform)):
+            self.skipTest(f"Test is not available on {sys.platform}.")
+
+        old_args = sys.argv
+        sys.argv = [test_info.module.__file__] + test_info.arguments
+
+        try:
+            with contextlib.redirect_stdout(io.StringIO()) as stdout_output:
+                with contextlib.redirect_stderr(io.StringIO()) as stderr_output:
+                    test_info.module.main()
+
+            stdout_text = stdout_output.getvalue()
+            stderr_text = stderr_output.getvalue()
+
+            if (test_info.error):
+                self.fail(f"No error was not raised when one was expected ('{str(test_info.expected_stdout)}').")
+        except BaseException as ex:
+            if (not test_info.error):
+                raise ex
+
+            stdout_text = self.format_error_string(ex)
+
+            stderr_text = ''
+            if (isinstance(ex, SystemExit) and (ex.__context__ is not None)):
+                stderr_text = self.format_error_string(ex.__context__)
+        finally:
+            sys.argv = old_args
+
+        if (test_info.stdout_assertion_func is not None):
+            test_info.stdout_assertion_func(self, test_info.expected_stdout, stdout_text)
+
+        if (test_info.stderr_assertion_func is not None):
+            test_info.stderr_assertion_func(self, test_info.expected_stderr, stderr_text)
+
+    return __method
+
+def add_test_paths(target_class: type, paths: typing.List[str]) -> None:
+    """ Add tests from the given test files. """
+
+    # Attach a temp directory to the testing class so all tests can share a common base temp dir.
+    if (not hasattr(target_class, BASE_TEMP_DIR_ATTR)):
+        setattr(target_class, BASE_TEMP_DIR_ATTR, edq.util.dirent.get_temp_path('edq_cli_test_'))
+
+    for path in sorted(paths):
+        test_name = 'test_cli__' + os.path.splitext(os.path.basename(path))[0]
+
+        try:
+            setattr(target_class, test_name, _get_test_method(test_name, path))
+        except Exception as ex:
+            raise ValueError(f"Failed to parse test case '{path}'.") from ex
+
+def discover_test_cases(target_class: type) -> None:
+    """ Look in the text cases directory for any test cases and add them as test methods to the test class. """
+
+    paths = list(sorted(glob.glob(os.path.join(TEST_CASES_DIR, "**", "*.txt"), recursive = True)))
+    add_test_paths(target_class, paths)

edq_utils-0.0.4/edq/testing/cli_test.py

@@ -0,0 +1,8 @@
+import edq.testing.cli
+import edq.testing.unittest
+
+class CLITest(edq.testing.unittest.BaseTest):
+    """ Test CLI invocations. """
+
+# Populate CLITest with all the test methods.
+edq.testing.cli.discover_test_cases(CLITest)

edq_utils-0.0.4/edq/testing/testdata/cli/tests/version_base.txt

@@ -0,0 +1,6 @@
+{
+    "cli": "edq.cli.version",
+    "arguments": [],
+}
+---
+<VERSION>

{edq_utils-0.0.3 → edq_utils-0.0.4}/edq/testing/unittest.py

@@ -14,7 +14,7 @@ class BaseTest(unittest.TestCase):
     maxDiff = None
     """ Don't limit the size of diffs. """
 
-    def assertJSONDictEqual(self, a: dict, b: dict) -> None:  # pylint: disable=invalid-name
+    def assertJSONDictEqual(self, a: typing.Dict[str, typing.Any], b: typing.Dict[str, typing.Any]) -> None:  # pylint: disable=invalid-name
         """
         Call assertDictEqual(), but supply a message containing the full JSON representation of the arguments.
         """
@@ -24,7 +24,7 @@ class BaseTest(unittest.TestCase):
 
         super().assertDictEqual(a, b, FORMAT_STR % (a_json, b_json))
 
-    def assertJSONListEqual(self, a: list, b: list) -> None:  # pylint: disable=invalid-name
+    def assertJSONListEqual(self, a: typing.List[typing.Any], b: typing.List[typing.Any]) -> None:  # pylint: disable=invalid-name
         """
         Call assertListEqual(), but supply a message containing the full JSON representation of the arguments.
         """

{edq_utils-0.0.3 → edq_utils-0.0.4}/edq/util/dirent.py

@@ -115,7 +115,7 @@ def remove(path: str) -> None:
     else:
         raise ValueError(f"Unknown type of dirent: '{path}'.")
 
-def same(a: str, b: str):
+def same(a: str, b: str) -> bool:
     """
     Check if two paths represent the same dirent.
     If either (or both) paths do not exist, false will be returned.
@@ -251,7 +251,7 @@ def write_file(
         raw_path: str, contents: typing.Union[str, None],
         strip: bool = True, newline: bool = True,
         encoding: str = DEFAULT_ENCODING,
-        no_clobber = False) -> None:
+        no_clobber: bool = False) -> None:
     """
     Write the contents of a file.
     If clobbering, any existing dirent will be removed before write.
@@ -290,7 +290,7 @@ def read_file_bytes(raw_path: str) -> bytes:
 
 def write_file_bytes(
         raw_path: str, contents: typing.Union[bytes, None],
-        no_clobber = False) -> None:
+        no_clobber: bool = False) -> None:
     """
     Write the contents of a file as bytes.
     If clobbering, any existing dirent will be removed before write.

{edq_utils-0.0.3 → edq_utils-0.0.4}/edq/util/json.py

@@ -47,7 +47,7 @@ class DictConverter(abc.ABC):
         if (type(self) != type(other)):  # pylint: disable=unidiomatic-typecheck
             return False
 
-        return self.to_dict() == other.to_dict()  # type: ignore[attr-defined]
+        return bool(self.to_dict() == other.to_dict())  # type: ignore[attr-defined]
 
     def __str__(self) -> str:
         return dumps(self)
@@ -68,11 +68,11 @@ def _custom_handle(value: typing.Any) -> typing.Union[typing.Dict[str, typing.An
         return str(value)
 
     if (hasattr(value, '__dict__')):
-        return vars(value)
+        return dict(vars(value))
 
     raise ValueError(f"Could not JSON serialize object: '{value}'.")
 
-def load(file_obj: typing.TextIO, strict: bool = False, **kwargs) -> typing.Dict[str, typing.Any]:
+def load(file_obj: typing.TextIO, strict: bool = False, **kwargs: typing.Any) -> typing.Any:
     """
     Load a file object/handler as JSON.
     If strict is set, then use standard Python JSON,
@@ -84,7 +84,7 @@ def load(file_obj: typing.TextIO, strict: bool = False, **kwargs) -> typing.Dict
 
     return json5.load(file_obj, **kwargs)
 
-def loads(text: str, strict: bool = False, **kwargs) -> typing.Dict[str, typing.Any]:
+def loads(text: str, strict: bool = False, **kwargs: typing.Any) -> typing.Any:
     """
     Load a string as JSON.
     If strict is set, then use standard Python JSON,
@@ -100,7 +100,7 @@ def load_path(
         path: str,
         strict: bool = False,
         encoding: str = edq.util.dirent.DEFAULT_ENCODING,
-        **kwargs) -> typing.Dict[str, typing.Any]:
+        **kwargs: typing.Any) -> typing.Any:
     """
     Load a file path as JSON.
     If strict is set, then use standard Python JSON,
@@ -113,30 +113,30 @@ def load_path(
     except Exception as ex:
         raise ValueError(f"Failed to read JSON file '{path}'.") from ex
 
-def loads_object(text: str, cls: typing.Type[DictConverter], **kwargs) -> DictConverter:
+def loads_object(text: str, cls: typing.Type[DictConverter], **kwargs: typing.Any) -> DictConverter:
     """ Load a JSON string into an object (which is a subclass of DictConverter). """
 
     data = loads(text, **kwargs)
     if (not isinstance(data, dict)):
         raise ValueError(f"JSON to load into an object is not a dict, found '{type(data)}'.")
 
-    return cls.from_dict(data)
+    return cls.from_dict(data)  # type: ignore[no-any-return]
 
-def load_object_path(path: str, cls: typing.Type[DictConverter], **kwargs) -> DictConverter:
+def load_object_path(path: str, cls: typing.Type[DictConverter], **kwargs: typing.Any) -> DictConverter:
     """ Load a JSON file into an object (which is a subclass of DictConverter). """
 
     data = load_path(path, **kwargs)
     if (not isinstance(data, dict)):
         raise ValueError(f"JSON to load into an object is not a dict, found '{type(data)}'.")
 
-    return cls.from_dict(data)
+    return cls.from_dict(data)  # type: ignore[no-any-return]
 
 def dump(
         data: typing.Any,
         file_obj: typing.TextIO,
         default: typing.Union[typing.Callable, None] = _custom_handle,
         sort_keys: bool = True,
-        **kwargs) -> None:
+        **kwargs: typing.Any) -> None:
     """ Dump an object as a JSON file object. """
 
     json.dump(data, file_obj, default = default, sort_keys = sort_keys, **kwargs)
@@ -145,7 +145,7 @@ def dumps(
         data: typing.Any,
         default: typing.Union[typing.Callable, None] = _custom_handle,
         sort_keys: bool = True,
-        **kwargs) -> str:
+        **kwargs: typing.Any) -> str:
     """ Dump an object as a JSON string. """
 
     return json.dumps(data, default = default, sort_keys = sort_keys, **kwargs)
@@ -156,7 +156,7 @@ def dump_path(
         default: typing.Union[typing.Callable, None] = _custom_handle,
         sort_keys: bool = True,
         encoding: str = edq.util.dirent.DEFAULT_ENCODING,
-        **kwargs) -> None:
+        **kwargs: typing.Any) -> None:
     """ Dump an object as a JSON file. """
 
     with open(path, 'w', encoding = encoding) as file:

{edq_utils-0.0.3 → edq_utils-0.0.4}/edq/util/pyimport.py

@@ -71,3 +71,24 @@ def import_name(module_name: str, cache: bool = True) -> typing.Any:
         _import_cache[cache_key] = module
 
     return module
+
+def fetch(name: str) -> typing.Any:
+    """
+    Fetch an entity inside of a module.
+    Note that the target is not a module, but an attribute/object inside of the module.
+    The provided name should be fully qualified.
+    """
+
+    parts = name.strip().rsplit('.', 1)
+    if (len(parts) != 2):
+        raise ValueError(f"Target name of fetch must be fully qualified, got '{name}'.")
+
+    module_name = parts[0]
+    short_name = parts[1]
+
+    module = import_name(module_name)
+
+    if (not hasattr(module, short_name)):
+        raise ValueError(f"Module '{module_name}' does not have attribute '{short_name}'.")
+
+    return getattr(module, short_name)

{edq_utils-0.0.3 → edq_utils-0.0.4}/edq/util/pyimport_test.py

@@ -81,3 +81,39 @@ class TestPyImport(edq.testing.unittest.BaseTest):
                     self.fail(f"Did not get expected error: '{error_substring}'.")
 
                 self.assertIsNotNone(module)
+
+    def test_fetch_base(self):
+        """ Test fetching an attribute from a module. """
+
+        # [(name, error substring), ...]
+        test_cases = [
+            # Standard Module
+            ('edq.util.pyimport.fetch', None),
+
+            # Errors
+            ('', 'Target name of fetch must be fully qualified'),
+            ('edq', 'Target name of fetch must be fully qualified'),
+            ('ZZZ.aaa', 'Unable to locate module'),
+            ('edq.ZZZ.aaa', 'Unable to locate module'),
+            ('edq.util.pyimport.ZZZ', 'does not have attribute'),
+        ]
+
+        for (i, test_case) in enumerate(test_cases):
+            (name, error_substring) = test_case
+
+            with self.subTest(msg = f"Case {i} ('{name}'):"):
+                try:
+                    target = edq.util.pyimport.fetch(name)
+                except Exception as ex:
+                    error_string = self.format_error_string(ex)
+                    if (error_substring is None):
+                        self.fail(f"Unexpected error: '{error_string}'.")
+
+                    self.assertIn(error_substring, error_string, 'Error is not as expected.')
+
+                    continue
+
+                if (error_substring is not None):
+                    self.fail(f"Did not get expected error: '{error_substring}'.")
+
+                self.assertIsNotNone(target)

{edq_utils-0.0.3 → edq_utils-0.0.4/edq_utils.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edq-utils
-Version: 0.0.3
+Version: 0.0.4
 Summary: Common utilities used by EduLinq Python projects.
 Author-email: Eriq Augustine <eriq@edulinq.org>
 License: MIT License

{edq_utils-0.0.3 → edq_utils-0.0.4}/edq_utils.egg-info/SOURCES.txt

@@ -5,9 +5,22 @@ requirements-dev.txt
 requirements.txt
 edq/__init__.py
 edq/py.typed
+edq/cli/__init__.py
+edq/cli/version.py
+edq/cli/testing/__init__.py
+edq/cli/testing/cli-test.py
+edq/core/__init__.py
+edq/core/argparser.py
+edq/core/argparser_test.py
+edq/core/log.py
+edq/core/version.py
 edq/testing/__init__.py
+edq/testing/asserts.py
+edq/testing/cli.py
+edq/testing/cli_test.py
 edq/testing/run.py
 edq/testing/unittest.py
+edq/testing/testdata/cli/tests/version_base.txt
 edq/util/__init__.py
 edq/util/dirent.py
 edq/util/dirent_test.py