edq-utils 0.2.3__py3-none-any.whl

edq/__init__.py

@@ -0,0 +1,5 @@
+"""
+General Python tools used by several EduLinq projects.
+"""
+
+__version__ = '0.2.3'

edq/cli/__main__.py

@@ -0,0 +1,17 @@
+"""
+The `edq.cli` package contains general tools for the EduLinq Python library.
+Each package can be invoked to list the tools (or subpackages) it contains.
+Each tool includes a help prompt that accessed with the `-h`/`--help` flag.
+"""
+
+import sys
+
+import edq.util.cli
+
+def main() -> int:
+    """ List this CLI dir. """
+
+    return edq.util.cli.main()
+
+if (__name__ == '__main__'):
+    sys.exit(main())

edq/cli/config/__init__.py

@@ -0,0 +1,3 @@
+"""
+The edq.cli.config package provides tools for working with project configuration options.
+"""

edq/cli/config/__main__.py

@@ -0,0 +1,15 @@
+"""
+The `edq.cli.config` package contains tools for interacting with configuration options.
+"""
+
+import sys
+
+import edq.util.cli
+
+def main() -> int:
+    """ List this CLI dir. """
+
+    return edq.util.cli.main()
+
+if (__name__ == '__main__'):
+    sys.exit(main())

edq/cli/config/list.py

@@ -0,0 +1,69 @@
+"""
+List the current configuration options.
+"""
+
+import argparse
+import sys
+
+import edq.core.argparser
+
+CONFIG_FIELD_SEPARATOR: str = "\t"
+
+def run_cli(args: argparse.Namespace) -> int:
+    """ Run the CLI. """
+
+    rows = []
+
+    for (key, value) in args._config.items():
+        row = [key, str(value)]
+        if (args.show_origin):
+            config_source_obj = args._config_sources.get(key)
+
+            origin = config_source_obj.path
+            if (origin is None):
+                origin = config_source_obj.label
+
+            row.append(origin)
+
+        rows.append(CONFIG_FIELD_SEPARATOR.join(row))
+
+    rows.sort()
+
+    if (not args.skip_header):
+        header = ["Key", "Value"]
+        if (args.show_origin):
+            header.append("Origin")
+
+        rows.insert(0, (CONFIG_FIELD_SEPARATOR.join(header)))
+
+    print("\n".join(rows))
+    return 0
+
+def main() -> int:
+    """ Get a parser, parse the args, and call run. """
+
+    return run_cli(_get_parser().parse_args())
+
+def _get_parser() -> argparse.ArgumentParser:
+    """ Get a parser and add addition flags. """
+
+    parser = edq.core.argparser.get_default_parser(__doc__.strip())
+    modify_parser(parser)
+
+    return parser
+
+def modify_parser(parser: argparse.ArgumentParser) -> None:
+    """ Add this CLI's flags to the given parser. """
+
+    parser.add_argument("--show-origin", dest = 'show_origin',
+        action = 'store_true',
+        help = "Display where each configuration's value was obtained from.",
+    )
+
+    parser.add_argument("--skip-header", dest = 'skip_header',
+        action = 'store_true',
+        help = 'Skip headers when displaying configs.',
+    )
+
+if (__name__ == '__main__'):
+    sys.exit(main())

edq/cli/http/__init__.py

@@ -0,0 +1,3 @@
+"""
+The edq.cli.http package provides CLI utilities involving HTTP.
+"""

edq/cli/http/__main__.py

@@ -0,0 +1,15 @@
+"""
+The `edq.cli.http` package contains tools for working with HTTP/web resources.
+"""
+
+import sys
+
+import edq.util.cli
+
+def main() -> int:
+    """ List this CLI dir. """
+
+    return edq.util.cli.main()
+
+if (__name__ == '__main__'):
+    sys.exit(main())

edq/cli/http/exchange-server.py

@@ -0,0 +1,71 @@
+# pylint: disable=invalid-name
+
+"""
+Start an HTTP test server that serves the specified HTTP exchanges.
+"""
+
+import argparse
+import os
+import sys
+
+import edq.core.argparser
+import edq.testing.httpserver
+
+def run_cli(args: argparse.Namespace) -> int:
+    """ Run the CLI. """
+
+    match_options = {
+        'params_to_skip': args.ignore_params,
+        'headers_to_skip': args.ignore_headers,
+    }
+
+    server = edq.testing.httpserver.HTTPTestServer(
+            port = args.port,
+            match_options = match_options,
+            verbose = True,
+            raise_on_404 = False,
+    )
+
+    for path in args.paths:
+        path = os.path.abspath(path)
+
+        if (os.path.isfile(path)):
+            server.load_exchange(path)
+        else:
+            server.load_exchanges_dir(path)
+
+    server.start_and_wait()
+
+    return 0
+
+def main() -> int:
+    """ Get a parser, parse the args, and call run. """
+    return run_cli(_get_parser().parse_args())
+
+def _get_parser() -> argparse.ArgumentParser:
+    """ Get the parser. """
+
+    parser = edq.core.argparser.get_default_parser(__doc__.strip(),
+            include_net = True,
+    )
+
+    parser.add_argument('paths', metavar = 'PATH',
+        type = str, nargs = '+',
+        help = 'Path to exchange files or dirs (which will be recursively searched for all exchange files).')
+
+    parser.add_argument('--port', dest = 'port',
+        action = 'store', type = int, default = None,
+        help = 'The port to run this test server on. If not set, a random open port will be chosen.')
+
+    parser.add_argument('--ignore-param', dest = 'ignore_params',
+        action = 'append', type = str, default = [],
+        help = 'Ignore this parameter during exchange matching.')
+
+    parser.add_argument('--ignore-header', dest = 'ignore_headers',
+        action = 'append', type = str, default = [],
+        help = 'Ignore this header during exchange matching.')
+
+    return parser
+
+if (__name__ == '__main__'):
+    sys.exit(main())

edq/cli/http/send-exchange.py

@@ -0,0 +1,45 @@
+# pylint: disable=invalid-name
+
+"""
+Send an HTTP exchange to the target server.
+"""
+
+import argparse
+import sys
+
+import edq.core.argparser
+import edq.util.net
+
+def run_cli(args: argparse.Namespace) -> int:
+    """ Run the CLI. """
+
+    exchange = edq.util.net.HTTPExchange.from_path(args.path)
+    _, body = exchange.make_request(args.server)
+
+    print(body)
+
+    return 0
+
+def main() -> int:
+    """ Get a parser, parse the args, and call run. """
+    return run_cli(_get_parser().parse_args())
+
+def _get_parser() -> argparse.ArgumentParser:
+    """ Get the parser. """
+
+    parser = edq.core.argparser.get_default_parser(__doc__.strip(),
+            include_net = True,
+    )
+
+    parser.add_argument('server', metavar = 'SERVER',
+        action = 'store', type = str,
+        help = 'Server to send the exahnge to.')
+
+    parser.add_argument('path', metavar = 'PATH',
+        action = 'store', type = str,
+        help = 'Path to the exchange file.')
+
+    return parser
+
+if (__name__ == '__main__'):
+    sys.exit(main())

edq/cli/http/verify-exchanges.py

@@ -0,0 +1,38 @@
+# pylint: disable=invalid-name
+
+"""
+Verify that exchanges sent to a given server have the same response.
+"""
+
+import argparse
+import sys
+
+import edq.core.argparser
+import edq.procedure.verify_exchanges
+
+def run_cli(args: argparse.Namespace) -> int:
+    """ Run the CLI. """
+
+    return edq.procedure.verify_exchanges.run(args.paths, args.server)
+
+def main() -> int:
+    """ Get a parser, parse the args, and call run. """
+    return run_cli(_get_parser().parse_args())
+
+def _get_parser() -> argparse.ArgumentParser:
+    """ Get the parser. """
+
+    parser = edq.core.argparser.get_default_parser(__doc__.strip())
+
+    parser.add_argument('server', metavar = 'SERVER',
+        action = 'store', type = str, default = None,
+        help = 'Address of the server to send exchanges to.')
+
+    parser.add_argument('paths', metavar = 'PATH',
+        type = str, nargs = '+',
+        help = 'Path to exchange files or dirs (which will be recursively searched for all exchange files).')
+
+    return parser
+
+if (__name__ == '__main__'):
+    sys.exit(main())

edq/cli/testing/__init__.py

@@ -0,0 +1,3 @@
+"""
+The edq.cli.testing package provides testing-related utilities.
+"""

edq/cli/testing/__main__.py

@@ -0,0 +1,15 @@
+"""
+The `edq.cli.testing` package contains tools for testing code.
+"""
+
+import sys
+
+import edq.util.cli
+
+def main() -> int:
+    """ List this CLI dir. """
+
+    return edq.util.cli.main()
+
+if (__name__ == '__main__'):
+    sys.exit(main())

edq/cli/testing/cli-test.py

@@ -0,0 +1,49 @@
+# 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.unittest
+
+class CLITest(edq.testing.unittest.BaseTest):
+    """ Test CLI invocations. """
+
+def run_cli(args: argparse.Namespace) -> int:
+    """ Run the CLI. """
+
+    edq.testing.cli.add_test_paths(CLITest, args.data_dir, args.paths)
+
+    runner = unittest.TextTestRunner(verbosity = 2)
+    tests = unittest.defaultTestLoader.loadTestsFromTestCase(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() -> argparse.ArgumentParser:
+    """ 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.')
+
+    parser.add_argument('--data-dir', dest = 'data_dir',
+        action = 'store', type = str, default = '.',
+        help = 'The additional data directory (expansion of __DATA_DIR__) used for tests (default: %(default)s).')
+
+    return parser
+
+if (__name__ == '__main__'):
+    sys.exit(main())

edq/cli/version.py

@@ -0,0 +1,28 @@
+"""
+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() -> argparse.ArgumentParser:
+    """ Get the parser. """
+
+    return edq.core.argparser.get_default_parser(__doc__.strip())
+
+if (__name__ == '__main__'):
+    sys.exit(main())

edq/core/argparser.py

@@ -0,0 +1,137 @@
+"""
+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 functools
+import typing
+
+import edq.core.config
+import edq.core.log
+import edq.util.net
+
+@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,
+        version: typing.Union[str, None] = None,
+        include_log: bool = True,
+        include_config: bool = True,
+        include_net: bool = False,
+        config_options: typing.Union[typing.Dict[str, typing.Any], None] = None,
+        ) -> Parser:
+    """ Get a parser with the requested default callbacks already attached. """
+
+    if (config_options is None):
+        config_options = {}
+
+    parser = Parser(description = description)
+
+    if (version is not None):
+        parser.add_argument('--version',
+                action = 'version', version = version)
+
+    if (include_log):
+        parser.register_callbacks('log', edq.core.log.set_cli_args, edq.core.log.init_from_args)
+
+    if (include_config):
+        config_pre_func = functools.partial(edq.core.config.set_cli_args, **config_options)
+        config_post_func = functools.partial(edq.core.config.load_config_into_args, **config_options)
+        parser.register_callbacks('config', config_pre_func, config_post_func)
+
+    if (include_net):
+        parser.register_callbacks('net', edq.util.net.set_cli_args, edq.util.net.init_from_args)
+
+    return parser

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)