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

{edq_utils-0.0.1 → edq_utils-0.0.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edq-utils
-Version: 0.0.1
+Version: 0.0.3
 Summary: Common utilities used by EduLinq Python projects.
 Author-email: Eriq Augustine <eriq@edulinq.org>
 License: MIT License
@@ -34,8 +34,10 @@ 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: twine; extra == "dev"
 Requires-Dist: vermin; extra == "dev"

edq_utils-0.0.3/edq/__init__.py

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

edq_utils-0.0.3/edq/testing/__init__.py

@@ -0,0 +1,3 @@
+"""
+Testing infrastructure.
+"""

edq_utils-0.0.3/edq/testing/run.py

@@ -0,0 +1,112 @@
+"""
+Discover and run unit tests (via Python's unittest package)
+that live in this project's base package
+(the parent of this package).
+"""
+
+import argparse
+import os
+import re
+import sys
+import typing
+import unittest
+
+DEFAULT_TEST_FILENAME_PATTERN: str = '*_test.py'
+
+def _collect_tests(suite: typing.Union[unittest.TestCase, unittest.suite.TestSuite]) -> typing.List[unittest.TestCase]:
+    """
+    Collect and return tests (unittest.TestCase) from the target directory.
+    """
+
+    if (isinstance(suite, unittest.TestCase)):
+        return [suite]
+
+    if (not isinstance(suite, unittest.suite.TestSuite)):
+        raise ValueError(f"Unknown test type: '{str(type(suite))}'.")
+
+    test_cases = []
+    for test_object in suite:
+        test_cases += _collect_tests(test_object)
+
+    return test_cases
+
+def run(args: argparse.Namespace) -> int:
+    """
+    Discover and run unit tests.
+    This function may change your working directory.
+    Will raise if tests fail to load (e.g. syntax errors) and a suggested exit code otherwise.
+    """
+
+    if (args.work_dir is not None):
+        os.chdir(args.work_dir)
+
+    if (args.path_additions is not None):
+        for path in args.path_additions:
+            sys.path.append(path)
+
+    if (args.test_dirs is None):
+        args.test_dirs = ['.']
+
+    runner = unittest.TextTestRunner(verbosity = 3)
+    test_cases = []
+
+    for test_dir in args.test_dirs:
+        discovered_suite = unittest.TestLoader().discover(test_dir, pattern = args.filename_pattern)
+        test_cases += _collect_tests(discovered_suite)
+
+    tests = unittest.suite.TestSuite()
+
+    for test_case in test_cases:
+        if (isinstance(test_case, unittest.loader._FailedTest)):  # type: ignore[attr-defined]
+            raise ValueError(f"Failed to load test: '{test_case.id()}'.") from test_case._exception
+
+        if (args.pattern is None or re.search(args.pattern, test_case.id())):
+            tests.addTest(test_case)
+        else:
+            print(f"Skipping {test_case.id()} because of match pattern.")
+
+    result = runner.run(tests)
+    faults = len(result.errors) + len(result.failures)
+
+    if (not result.wasSuccessful()):
+        # This value will be used as an exit status, so it should not be larger than a byte.
+        # (Some higher values are used specially, so just keep it at a round number.)
+        return max(1, min(faults, 100))
+
+    return 0
+
+def main() -> int:
+    """ Parse the CLI arguments and run tests. """
+
+    args = _get_parser().parse_args()
+    return run(args)
+
+def _get_parser() -> argparse.ArgumentParser:
+    """ Build a parser for CLI arguments. """
+
+    parser = argparse.ArgumentParser(description = 'Run unit tests discovered in this project.')
+
+    parser.add_argument('--work-dir', dest = 'work_dir',
+        action = 'store', type = str, default = os.getcwd(),
+        help = 'Set the working directory when running tests, defaults to the current working directory (%(default)s).')
+
+    parser.add_argument('--tests-dir', dest = 'test_dirs',
+        action = 'append',
+        help = 'Discover tests from these directories. Defaults to the current directory.')
+
+    parser.add_argument('--add-path', dest = 'path_additions',
+        action = 'append',
+        help = 'If supplied, add this path the sys.path before running tests.')
+
+    parser.add_argument('--filename-pattern', dest = 'filename_pattern',
+        action = 'store', type = str, default = DEFAULT_TEST_FILENAME_PATTERN,
+        help = 'The pattern to use to find test files (default: %(default)s).')
+
+    parser.add_argument('pattern',
+        action = 'store', type = str, default = None, nargs = '?',
+        help = 'If supplied, only tests with names matching this pattern will be run. This pattern is used directly in re.search().')
+
+    return parser
+
+if __name__ == '__main__':
+    sys.exit(main())

edq_utils-0.0.3/edq/testing/unittest.py

@@ -0,0 +1,54 @@
+import typing
+import unittest
+
+import edq.util.json
+import edq.util.reflection
+
+FORMAT_STR: str = "\n--- Expected ---\n%s\n--- Actual ---\n%s\n---\n"
+
+class BaseTest(unittest.TestCase):
+    """
+    A base class for unit tests.
+    """
+
+    maxDiff = None
+    """ Don't limit the size of diffs. """
+
+    def assertJSONDictEqual(self, a: dict, b: dict) -> None:  # pylint: disable=invalid-name
+        """
+        Call assertDictEqual(), but supply a message containing the full JSON representation of the arguments.
+        """
+
+        a_json = edq.util.json.dumps(a, indent = 4)
+        b_json = edq.util.json.dumps(b, indent = 4)
+
+        super().assertDictEqual(a, b, FORMAT_STR % (a_json, b_json))
+
+    def assertJSONListEqual(self, a: list, b: list) -> None:  # pylint: disable=invalid-name
+        """
+        Call assertListEqual(), but supply a message containing the full JSON representation of the arguments.
+        """
+
+        a_json = edq.util.json.dumps(a, indent = 4)
+        b_json = edq.util.json.dumps(b, indent = 4)
+
+        super().assertListEqual(a, b, FORMAT_STR % (a_json, b_json))
+
+    def format_error_string(self, ex: typing.Union[BaseException, None]) -> str:
+        """
+        Format an error string from an exception so it can be checked for testing.
+        The type of the error will be included,
+        and any nested errors will be joined together.
+        """
+
+        parts = []
+
+        while (ex is not None):
+            type_name = edq.util.reflection.get_qualified_name(ex)
+            message = str(ex)
+
+            parts.append(f"{type_name}: {message}")
+
+            ex = ex.__cause__
+
+        return "; ".join(parts)

edq_utils-0.0.3/edq/util/__init__.py

@@ -0,0 +1,3 @@
+"""
+Low-level utilities.
+"""

edq_utils-0.0.3/edq/util/dirent.py

@@ -0,0 +1,338 @@
+"""
+Operations relating to directory entries (dirents).
+
+These operations are designed for clarity and compatibility, not performance.
+
+Only directories, files, and links will be handled.
+Other types of dirents may result in an error being raised.
+
+In general, all recursive operations do not follow symlinks by default and instead treat the link as a file.
+"""
+
+import atexit
+import os
+import shutil
+import tempfile
+import typing
+import uuid
+
+DEFAULT_ENCODING: str = 'utf-8'
+""" The default encoding that will be used when reading and writing. """
+
+DEPTH_LIMIT: int = 10000
+
+def exists(path: str) -> bool:
+    """
+    Check if a path exists.
+    This will transparently call os.path.lexists(),
+    which will include broken links.
+    """
+
+    return os.path.lexists(path)
+
+def get_temp_path(prefix: str = '', suffix: str = '', rm: bool = True) -> str:
+    """
+    Get a path to a valid (but not currently existing) temp dirent.
+    If rm is True, then the dirent will be attempted to be deleted on exit
+    (no error will occur if the path is not there).
+    """
+
+    path = None
+    while ((path is None) or exists(path)):
+        path = os.path.join(tempfile.gettempdir(), prefix + str(uuid.uuid4()) + suffix)
+
+    if (rm):
+        atexit.register(remove, path)
+
+    return path
+
+def get_temp_dir(prefix: str = '', suffix: str = '', rm: bool = True) -> str:
+    """
+    Get a temp directory.
+    The directory will exist when returned.
+    """
+
+    path = get_temp_path(prefix = prefix, suffix = suffix, rm = rm)
+    mkdir(path)
+    return path
+
+def mkdir(raw_path: str) -> None:
+    """
+    Make a directory (including any required parent directories).
+    Does not complain if the directory (or parents) already exist
+    (this includes if the directory or parents are links to directories).
+    """
+
+    path = os.path.abspath(raw_path)
+
+    if (exists(path)):
+        if (os.path.isdir(path)):
+            return
+
+        raise ValueError(f"Target of mkdir already exists, and is not a dir: '{raw_path}'.")
+
+    _check_parent_dirs(raw_path)
+
+    os.makedirs(path, exist_ok = True)
+
+def _check_parent_dirs(raw_path: str) -> None:
+    """
+    Check all parents to ensure that they are all dirs (or don't exist).
+    This is naturally handled by os.makedirs(),
+    but the error messages are not consistent between POSIX and Windows.
+    """
+
+    path = os.path.abspath(raw_path)
+
+    parent_path = path
+    for _ in range(DEPTH_LIMIT):
+        new_parent_path = os.path.dirname(parent_path)
+        if (parent_path == new_parent_path):
+            # We have reached root (are our own parent).
+            return
+
+        parent_path = new_parent_path
+
+        if (os.path.exists(parent_path) and (not os.path.isdir(parent_path))):
+            raise ValueError(f"Target of mkdir contains parent ('{os.path.basename(parent_path)}') that exists and is not a dir: '{raw_path}'.")
+
+    raise ValueError("Depth limit reached.")
+
+def remove(path: str) -> None:
+    """
+    Remove the given path.
+    The path can be of any type (dir, file, link),
+    and does not need to exist.
+    """
+
+    if (not exists(path)):
+        return
+
+    if (os.path.isfile(path) or os.path.islink(path)):
+        os.remove(path)
+    elif (os.path.isdir(path)):
+        shutil.rmtree(path)
+    else:
+        raise ValueError(f"Unknown type of dirent: '{path}'.")
+
+def same(a: str, b: str):
+    """
+    Check if two paths represent the same dirent.
+    If either (or both) paths do not exist, false will be returned.
+    If either paths are links, they are resolved before checking
+    (so a link and the target file are considered the "same").
+    """
+
+    return (exists(a) and exists(b) and os.path.samefile(a, b))
+
+def move(raw_source: str, raw_dest: str, no_clobber: bool = False) -> None:
+    """
+    Move the source dirent to the given destination.
+    Any existing destination will be removed before moving.
+    """
+
+    source = os.path.abspath(raw_source)
+    dest = os.path.abspath(raw_dest)
+
+    if (not exists(source)):
+        raise ValueError(f"Source of move does not exist: '{raw_source}'.")
+
+    # If dest is a dir, then resolve the path.
+    if (os.path.isdir(dest)):
+        dest = os.path.abspath(os.path.join(dest, os.path.basename(source)))
+
+    # Skip if this is self.
+    if (same(source, dest)):
+        return
+
+    # Check for clobber.
+    if (exists(dest)):
+        if (no_clobber):
+            raise ValueError(f"Destination of move already exists: '{raw_dest}'.")
+
+        remove(dest)
+
+    # Create any required parents.
+    os.makedirs(os.path.dirname(dest), exist_ok = True)
+
+    shutil.move(source, dest)
+
+def copy(raw_source: str, raw_dest: str, no_clobber: bool = False) -> None:
+    """
+    Copy a dirent or directory to a destination.
+
+    The destination will be overwritten if it exists (and no_clobber is false).
+    For copying the contents of a directory INTO another directory, use copy_contents().
+
+    No copy is made if the source and dest refer to the same dirent.
+    """
+
+    source = os.path.abspath(raw_source)
+    dest = os.path.abspath(raw_dest)
+
+    if (same(source, dest)):
+        return
+
+    if (not exists(source)):
+        raise ValueError(f"Source of copy does not exist: '{raw_source}'.")
+
+    if (exists(dest)):
+        if (no_clobber):
+            raise ValueError(f"Destination of copy already exists: '{raw_dest}'.")
+
+        if (contains_path(dest, source)):
+            raise ValueError(f"Destination of copy cannot contain the source. Destination: '{raw_dest}', Source: '{raw_source}'.")
+
+        remove(dest)
+
+    mkdir(os.path.dirname(dest))
+
+    if (os.path.islink(source)):
+        # shutil.copy2() can generally handle (broken) links, but Windows is inconsistent (between 3.11 and 3.12) on link handling.
+        link_target = os.readlink(source)
+        os.symlink(link_target, dest)
+    elif (os.path.isfile(source)):
+        shutil.copy2(source, dest, follow_symlinks = False)
+    elif (os.path.isdir(source)):
+        mkdir(dest)
+
+        for child in sorted(os.listdir(source)):
+            copy(os.path.join(raw_source, child), os.path.join(raw_dest, child))
+    else:
+        raise ValueError(f"Source of copy is not a dir, fie, or link: '{raw_source}'.")
+
+def copy_contents(raw_source: str, raw_dest: str, no_clobber: bool = False) -> None:
+    """
+    Copy a file or the contents of a directory (excluding the top-level directory itself) into a destination.
+    If the destination exists, it must be a directory.
+
+    The source and destination should not be the same file.
+
+    For a file, this is equivalent to `mkdir -p dest && cp source dest`
+    For a dir, this is equivalent to `mkdir -p dest && cp -r source/* dest`
+    """
+
+    source = os.path.abspath(raw_source)
+    dest = os.path.abspath(raw_dest)
+
+    if (same(source, dest)):
+        raise ValueError(f"Source and destination of contents copy cannot be the same: '{raw_source}'.")
+
+    if (exists(dest) and (not os.path.isdir(dest))):
+        raise ValueError(f"Destination of contents copy exists and is not a dir: '{raw_dest}'.")
+
+    mkdir(dest)
+
+    if (os.path.isfile(source) or os.path.islink(source)):
+        copy(source, os.path.join(dest, os.path.basename(source)), no_clobber = no_clobber)
+    elif (os.path.isdir(source)):
+        for child in sorted(os.listdir(source)):
+            copy(os.path.join(raw_source, child), os.path.join(raw_dest, child), no_clobber = no_clobber)
+    else:
+        raise ValueError(f"Source of contents copy is not a dir, fie, or link: '{raw_source}'.")
+
+def read_file(raw_path: str, strip: bool = True, encoding: str = DEFAULT_ENCODING) -> str:
+    """ Read the contents of a file. """
+
+    path = os.path.abspath(raw_path)
+
+    if (not exists(path)):
+        raise ValueError(f"Source of read does not exist: '{raw_path}'.")
+
+    with open(path, 'r', encoding = encoding) as file:
+        contents = file.read()
+
+    if (strip):
+        contents = contents.strip()
+
+    return contents
+
+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:
+    """
+    Write the contents of a file.
+    If clobbering, any existing dirent will be removed before write.
+    """
+
+    path = os.path.abspath(raw_path)
+
+    if (exists(path)):
+        if (no_clobber):
+            raise ValueError(f"Destination of write already exists: '{raw_path}'.")
+
+        remove(path)
+
+    if (contents is None):
+        contents = ''
+
+    if (strip):
+        contents = contents.strip()
+
+    if (newline):
+        contents += "\n"
+
+    with open(path, 'w', encoding = encoding) as file:
+        file.write(contents)
+
+def read_file_bytes(raw_path: str) -> bytes:
+    """ Read the contents of a file as bytes. """
+
+    path = os.path.abspath(raw_path)
+
+    if (not exists(path)):
+        raise ValueError(f"Source of read bytes does not exist: '{raw_path}'.")
+
+    with open(path, 'rb') as file:
+        return file.read()
+
+def write_file_bytes(
+        raw_path: str, contents: typing.Union[bytes, None],
+        no_clobber = False) -> None:
+    """
+    Write the contents of a file as bytes.
+    If clobbering, any existing dirent will be removed before write.
+    """
+
+    path = os.path.abspath(raw_path)
+
+    if (exists(path)):
+        if (no_clobber):
+            raise ValueError(f"Destination of write bytes already exists: '{raw_path}'.")
+
+        remove(path)
+
+    if (contents is None):
+        contents = b''
+
+    with open(path, 'wb') as file:
+        file.write(contents)
+
+def contains_path(parent: str, child: str) -> bool:
+    """
+    Check if the parent path contains the child path.
+    This is pure lexical analysis, no dirent stats are checked.
+    Will return false if the (absolute) paths are the same
+    (this function does not allow a path to contain itself).
+    """
+
+    if ((parent == '') or (child == '')):
+        return False
+
+    parent = os.path.abspath(parent)
+    child = os.path.abspath(child)
+
+    child = os.path.dirname(child)
+    for _ in range(DEPTH_LIMIT):
+        if (parent == child):
+            return True
+
+        new_child = os.path.dirname(child)
+        if (child == new_child):
+            return False
+
+        child = new_child
+
+    raise ValueError("Depth limit reached.")