edq-utils 0.0.5__tar.gz → 0.0.7__tar.gz

edq_utils-0.0.7/.mypy.ini

@@ -0,0 +1,12 @@
+[mypy]
+
+exclude = _test\.py$
+
+strict = false
+disable_error_code = type-arg
+
+[mypy-requests.*]
+ignore_missing_imports = True
+
+[mypy-requests_toolbelt.*]
+ignore_missing_imports = True

{edq_utils-0.0.5 → edq_utils-0.0.7}/.pylintrc

@@ -444,9 +444,11 @@ disable=bad-inline-option,
         too-many-arguments,
         too-many-branches,
         too-many-instance-attributes,
+        too-many-lines,
         too-many-locals,
         too-many-positional-arguments,
         too-many-public-methods,
+        too-many-return-statements,
         too-many-statements,
         unused-argument,
         use-symbolic-message-instead,

edq_utils-0.0.7/PKG-INFO

@@ -0,0 +1,156 @@
+Metadata-Version: 2.4
+Name: edq-utils
+Version: 0.0.7
+Summary: Common utilities used by EduLinq Python projects.
+Author-email: Eriq Augustine <eriq@edulinq.org>
+License: MIT License
+        
+        Copyright (c) 2025 EduLinq
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/edulinq/python-utils
+Project-URL: Repository, https://github.com/edulinq/python-utils
+Keywords: education,utilities
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.8
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: json5>=0.9.14
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.1; extra == "dev"
+Requires-Dist: pdoc>=14.7.0; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: requests-toolbelt; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: vermin; extra == "dev"
+Dynamic: license-file
+
+# EduLinq Python Utilities
+
+Common utilities used by EduLinq Python projects.
+
+## Installation / Requirements
+
+This project requires [Python](https://www.python.org/) >= 3.8.
+
+The project can be installed from PyPi with:
+```
+pip3 install edq-utils
+```
+
+Standard Python requirements are listed in `pyproject.toml`.
+The project and Python dependencies can be installed from source with:
+```
+pip3 install .
+```
+
+## Configuration System
+
+This project provides a configuration system that supplies options (e.g., username, password) to a command-line interface (CLI) tool.
+The configuration system follows a tiered order, allowing options to be specified and overridden from both files and command-line options.
+
+### Configuration Sources
+
+In addition to CLI options, the configuration system loads options from [JSON](https://en.wikipedia.org/wiki/JSON) files located across multiple directories.
+By default, configuration files are named `edq-config.json`.
+This value is customizable, but this document will assume the default is used.
+
+For example, a configuration file containing the `user` and `pass` options might look like this:
+```json
+{
+    "user": "alice",
+    "pass": "password123"
+}
+```
+
+The table below summarizes the configuration sources in the order they are evaluated.
+Values from earlier sources can be overwritten by values from later sources.
+
+| Source   | Description |
+| :-----   | :---------- |
+| Global   | Loaded from a file in a user-specific location, which is platform-dependent. |
+| Local    | Loaded from a file in the current or nearest ancestor directory. |
+| CLI File | Loaded from one or more explicitly provided configuration files through the CLI. |
+| CLI      | Loaded from the command line. |
+
+The system produces an error if a global or local configuration file is unreadable (but not missing), or if a CLI-specified file is unreadable or missing.
+
+#### Global Configuration
+
+Global configuration are options that are user specific and stick with the user between projects, these are well suited for options like login credentials.
+The global configuration file defaults to `<platform-specific user configuration location>/edq-config.json`.
+The configuration location is chosen according to the [XDG standard](https://en.wikipedia.org/wiki/Freedesktop.org#Base_Directory_Specification) (implemented by [platformdirs](https://github.com/tox-dev/platformdirs)).
+Below are examples of user-specific configuration file paths for different operating systems:
+ - Linux -- `/home/<user>/.config/edq-config.json`
+ - Mac -- `/Users/<user>/Library/Application Support/edq-config.json`
+ - Windows -- `C:\Users\<user>\AppData\Local\edq-config.json`
+
+The default global configuration location can be changed by passing a path to `--config-global` through the command line.
+
+Below is an example command for specifying a global configuration path from the CLI:
+```sh
+python3 -m edq.cli.config.list --config-global  ~/.config/custom-config.json
+```
+
+#### Local Configuration
+
+Local configuration are options that are specific to a project or directory, like a project's build directory.
+Local configuration files are searched in multiple locations, the first file found is used.
+The local config search order is:
+1. `edq-config.json` in the current directory.
+2. A legacy file in the current directory (only if a legacy file is preconfigured).
+3. `edq-config.json` in any ancestor directory on the path to root (including root itself).
+
+#### CLI-Specified Config Files
+
+CLI config files are options specified on the command line via a file.
+These are useful for a common set of options you don’t need every time, such as login credentials for different user.
+Any files passed via `--config-file` will be loaded in the order they appear on the command line.
+Options from later files override options from previous files.
+
+Below is an example of a CLI specified configuration paths:
+```sh
+python3 -m edq.cli.config.list --config-file ./edq-config.json --config-file ~/.secrets/edq-config.json
+```
+
+#### CLI Configuration
+
+CLI configurations are options specified directly on the command line, these are useful for quick option overrides without editing config files.
+Configuration options are passed to the command line by the `--config` flag in this format `<key>=<value>`.
+The provided values overrides the values from configuration files.
+Configuration options are structured as key value pairs and keys cannot contain the "=" character.
+
+Below is an example of specifying a configuration option directly from the CLI:
+```sh
+python3 -m edq.cli.config.list --config user=alice --config pass=password123
+```
+
+#### CLI Config Options
+
+The table below lists common configuration CLI options available for CLI tools using this library.
+
+| CLI Option       | Description |
+| :--------------  | :---------- |
+|`--config-global` | Override the global config file location. |
+|`--config-file`   | Load configuration options from a CLI specified file. |
+| `--config`       | Provide additional options to a CLI command. |
+| `--help`         | Display standard help text and the default global configuration file path for the current platform. |

edq_utils-0.0.7/README.md

@@ -0,0 +1,110 @@
+# EduLinq Python Utilities
+
+Common utilities used by EduLinq Python projects.
+
+## Installation / Requirements
+
+This project requires [Python](https://www.python.org/) >= 3.8.
+
+The project can be installed from PyPi with:
+```
+pip3 install edq-utils
+```
+
+Standard Python requirements are listed in `pyproject.toml`.
+The project and Python dependencies can be installed from source with:
+```
+pip3 install .
+```
+
+## Configuration System
+
+This project provides a configuration system that supplies options (e.g., username, password) to a command-line interface (CLI) tool.
+The configuration system follows a tiered order, allowing options to be specified and overridden from both files and command-line options.
+
+### Configuration Sources
+
+In addition to CLI options, the configuration system loads options from [JSON](https://en.wikipedia.org/wiki/JSON) files located across multiple directories.
+By default, configuration files are named `edq-config.json`.
+This value is customizable, but this document will assume the default is used.
+
+For example, a configuration file containing the `user` and `pass` options might look like this:
+```json
+{
+    "user": "alice",
+    "pass": "password123"
+}
+```
+
+The table below summarizes the configuration sources in the order they are evaluated.
+Values from earlier sources can be overwritten by values from later sources.
+
+| Source   | Description |
+| :-----   | :---------- |
+| Global   | Loaded from a file in a user-specific location, which is platform-dependent. |
+| Local    | Loaded from a file in the current or nearest ancestor directory. |
+| CLI File | Loaded from one or more explicitly provided configuration files through the CLI. |
+| CLI      | Loaded from the command line. |
+
+The system produces an error if a global or local configuration file is unreadable (but not missing), or if a CLI-specified file is unreadable or missing.
+
+#### Global Configuration
+
+Global configuration are options that are user specific and stick with the user between projects, these are well suited for options like login credentials.
+The global configuration file defaults to `<platform-specific user configuration location>/edq-config.json`.
+The configuration location is chosen according to the [XDG standard](https://en.wikipedia.org/wiki/Freedesktop.org#Base_Directory_Specification) (implemented by [platformdirs](https://github.com/tox-dev/platformdirs)).
+Below are examples of user-specific configuration file paths for different operating systems:
+ - Linux -- `/home/<user>/.config/edq-config.json`
+ - Mac -- `/Users/<user>/Library/Application Support/edq-config.json`
+ - Windows -- `C:\Users\<user>\AppData\Local\edq-config.json`
+
+The default global configuration location can be changed by passing a path to `--config-global` through the command line.
+
+Below is an example command for specifying a global configuration path from the CLI:
+```sh
+python3 -m edq.cli.config.list --config-global  ~/.config/custom-config.json
+```
+
+#### Local Configuration
+
+Local configuration are options that are specific to a project or directory, like a project's build directory.
+Local configuration files are searched in multiple locations, the first file found is used.
+The local config search order is:
+1. `edq-config.json` in the current directory.
+2. A legacy file in the current directory (only if a legacy file is preconfigured).
+3. `edq-config.json` in any ancestor directory on the path to root (including root itself).
+
+#### CLI-Specified Config Files
+
+CLI config files are options specified on the command line via a file.
+These are useful for a common set of options you don’t need every time, such as login credentials for different user.
+Any files passed via `--config-file` will be loaded in the order they appear on the command line.
+Options from later files override options from previous files.
+
+Below is an example of a CLI specified configuration paths:
+```sh
+python3 -m edq.cli.config.list --config-file ./edq-config.json --config-file ~/.secrets/edq-config.json
+```
+
+#### CLI Configuration
+
+CLI configurations are options specified directly on the command line, these are useful for quick option overrides without editing config files.
+Configuration options are passed to the command line by the `--config` flag in this format `<key>=<value>`.
+The provided values overrides the values from configuration files.
+Configuration options are structured as key value pairs and keys cannot contain the "=" character.
+
+Below is an example of specifying a configuration option directly from the CLI:
+```sh
+python3 -m edq.cli.config.list --config user=alice --config pass=password123
+```
+
+#### CLI Config Options
+
+The table below lists common configuration CLI options available for CLI tools using this library.
+
+| CLI Option       | Description |
+| :--------------  | :---------- |
+|`--config-global` | Override the global config file location. |
+|`--config-file`   | Load configuration options from a CLI specified file. |
+| `--config`       | Provide additional options to a CLI command. |
+| `--help`         | Display standard help text and the default global configuration file path for the current platform. |

{edq_utils-0.0.5 → edq_utils-0.0.7}/edq/__init__.py

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

edq_utils-0.0.7/edq/cli/config/__init__.py

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

edq_utils-0.0.7/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_utils-0.0.7/edq/cli/http/__init__.py

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

edq_utils-0.0.7/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_utils-0.0.7/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_utils-0.0.7/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_utils-0.0.7/edq/cli/testing/__init__.py

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

{edq_utils-0.0.5 → edq_utils-0.0.7}/edq/cli/testing/cli-test.py

@@ -1,4 +1,4 @@
-#  # pylint: disable=invalid-name
+# pylint: disable=invalid-name
 
 """
 Run specified CLI test files.
@@ -10,15 +10,18 @@ import unittest
 
 import edq.core.argparser
 import edq.testing.cli
-import edq.testing.cli_test
+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(edq.testing.cli_test.CLITest, args.data_dir, args.paths)
+    edq.testing.cli.add_test_paths(CLITest, args.data_dir, args.paths)
 
     runner = unittest.TextTestRunner(verbosity = 2)
-    tests = unittest.defaultTestLoader.loadTestsFromTestCase(edq.testing.cli_test.CLITest)
+    tests = unittest.defaultTestLoader.loadTestsFromTestCase(CLITest)
     results = runner.run(tests)
 
     return len(results.errors) + len(results.failures)
@@ -27,7 +30,7 @@ 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:
+def _get_parser() -> argparse.ArgumentParser:
     """ Get the parser. """
 
     parser = edq.core.argparser.get_default_parser(__doc__.strip())

{edq_utils-0.0.5 → edq_utils-0.0.7}/edq/cli/version.py

@@ -16,9 +16,10 @@ def run_cli(args: argparse.Namespace) -> int:
 
 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:
+def _get_parser() -> argparse.ArgumentParser:
     """ Get the parser. """
 
     return edq.core.argparser.get_default_parser(__doc__.strip())

{edq_utils-0.0.5 → edq_utils-0.0.7}/edq/core/argparser.py

@@ -8,9 +8,12 @@ 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):
@@ -102,11 +105,33 @@ class Parser(argparse.ArgumentParser):
 
         return parsed_args  # type: ignore[no-any-return]
 
-def get_default_parser(description: str) -> Parser:
-    """ Get a parser with the default callbacks already attached. """
+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)
 
-    parser.register_callbacks('log', edq.core.log.set_cli_args, edq.core.log.init_from_args)
+    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