edq-utils 0.0.2__py3-none-any.whl → 0.0.4__py3-none-any.whl

edq/util/json.py

@@ -4,6 +4,8 @@ Specifically, we try to be flexible when reading (using JSON5),
 and strict when writing (using vanilla JSON).
 """
 
+import abc
+import enum
 import json
 import typing
 
@@ -11,7 +13,66 @@ import json5
 
 import edq.util.dirent
 
-def load(file_obj: typing.TextIO, strict: bool = False, **kwargs) -> typing.Dict[str, typing.Any]:
+class DictConverter(abc.ABC):
+    """
+    A base class for class that can represent (serialize) and reconstruct (deserialize) themselves as/from a dict.
+    The intention is that the dict can then be cleanly converted to/from JSON.
+    """
+
+    @abc.abstractmethod
+    def to_dict(self) -> typing.Dict[str, typing.Any]:
+        """
+        Return a dict that can be used to represent this object.
+        If the dict is passed to from_dict(), an identical object should be reconstructed.
+        """
+
+    @classmethod
+    @abc.abstractmethod
+    # Note that `typing.Self` is returned, but that is introduced in Python 3.12.
+    def from_dict(cls, data: typing.Dict[str, typing.Any]) -> typing.Any:
+        """
+        Return an instance of this subclass created using the given dict.
+        If the dict came from to_dict(), the returned object should be identical to the original.
+        """
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Check for equality.
+
+        This check uses to_dict() and compares the results.
+        This may not be complete or efficient depending on the child class.
+        """
+
+        # Note the hard type check (done so we can keep this method general).
+        if (type(self) != type(other)):  # pylint: disable=unidiomatic-typecheck
+            return False
+
+        return bool(self.to_dict() == other.to_dict())  # type: ignore[attr-defined]
+
+    def __str__(self) -> str:
+        return dumps(self)
+
+    def __repr__(self) -> str:
+        return dumps(self)
+
+def _custom_handle(value: typing.Any) -> typing.Union[typing.Dict[str, typing.Any], str]:
+    """
+    Handle objects that are not JSON serializable by default,
+    e.g., calling vars() on an object.
+    """
+
+    if (isinstance(value, DictConverter)):
+        return value.to_dict()
+
+    if (isinstance(value, enum.Enum)):
+        return str(value)
+
+    if (hasattr(value, '__dict__')):
+        return dict(vars(value))
+
+    raise ValueError(f"Could not JSON serialize object: '{value}'.")
+
+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,
@@ -23,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,
@@ -39,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,
@@ -52,29 +113,51 @@ 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: 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)  # type: ignore[no-any-return]
+
+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)  # 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, sort_keys = sort_keys, **kwargs)
+    json.dump(data, file_obj, default = default, sort_keys = sort_keys, **kwargs)
 
 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, sort_keys = sort_keys, **kwargs)
+    return json.dumps(data, default = default, sort_keys = sort_keys, **kwargs)
 
 def dump_path(
         data: typing.Any,
         path: str,
+        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:
-        dump(data, file, **kwargs)
+        dump(data, file, default = default, sort_keys = sort_keys, **kwargs)

edq/util/json_test.py

@@ -1,4 +1,5 @@
 import os
+import typing
 
 import edq.testing.unittest
 import edq.util.dirent
@@ -80,10 +81,10 @@ class TestJSON(edq.testing.unittest.BaseTest):
     def _subtest_loads_dumps(self, text_content, dict_content, strict):
         actual_dict = edq.util.json.loads(text_content, strict = strict)
         actual_text = edq.util.json.dumps(dict_content)
-        double_conversion_dict = edq.util.json.dumps(actual_dict)
+        double_conversion_text = edq.util.json.dumps(actual_dict)
 
         self.assertDictEqual(dict_content, actual_dict)
-        self.assertEqual(actual_text, double_conversion_dict)
+        self.assertEqual(actual_text, double_conversion_text)
 
     def _subtest_load_dump(self, text_content, dict_content, strict):
         temp_dir = edq.util.dirent.get_temp_dir(prefix = 'edq_test_json_')
@@ -119,3 +120,109 @@ class TestJSON(edq.testing.unittest.BaseTest):
 
         self.assertDictEqual(dict_content, text_load)
         self.assertDictEqual(dict_load, text_load)
+
+    def test_object_base(self):
+        """
+        Test loading and dumping JSON objects
+        """
+
+        # [(string, object, error_substring), ...]
+        test_cases = [
+            # Base
+            (
+                '{"a": 1, "b": "b"}',
+                _TestConverter(1, "b"),
+                None,
+            ),
+
+            # Missing Key
+            (
+                '{"a": 1}',
+                _TestConverter(1, None),
+                None,
+            ),
+
+            # Empty
+            (
+                '{}',
+                _TestConverter(None, None),
+                None,
+            ),
+
+            # Extra Key
+            (
+                '{"a": 1, "b": "b", "c": 0}',
+                _TestConverter(1, "b"),
+                None,
+            ),
+
+            # List
+            (
+                '[{"a": 1, "b": "b"}]',
+                _TestConverter(1, "b"),
+                'not a dict',
+            ),
+        ]
+
+        # [(function, name), ...]
+        test_methods = [
+            (self._subtest_loads_object, 'subtest_loads_object'),
+            (self._subtest_load_object_path, 'subtest_load_object_path'),
+        ]
+
+        for (test_method, test_method_name) in test_methods:
+            for (i, test_case) in enumerate(test_cases):
+                (text_content, object_content, error_substring) = test_case
+
+                with self.subTest(msg = f"Subtest {test_method_name}, Case {i} ('{text_content}'):"):
+                    try:
+                        test_method(text_content, object_content)
+                    except AssertionError:
+                        # The subttest failed an assertion.
+                        raise
+                    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}'.")
+
+    def _subtest_loads_object(self, text_content, object_content):
+        actual_object = edq.util.json.loads_object(text_content, _TestConverter)
+        actual_text = edq.util.json.dumps(object_content)
+        double_conversion_text = edq.util.json.dumps(actual_object)
+
+        self.assertEqual(object_content, actual_object)
+        self.assertEqual(actual_text, double_conversion_text)
+
+    def _subtest_load_object_path(self, text_content, object_content):
+        temp_dir = edq.util.dirent.get_temp_dir(prefix = 'edq_test_json_object_path_')
+
+        path_text = os.path.join(temp_dir, 'test-text.json')
+        path_object = os.path.join(temp_dir, 'test-object.json')
+
+        edq.util.dirent.write_file(path_text, text_content)
+        text_load = edq.util.json.load_object_path(path_text, _TestConverter)
+
+        edq.util.json.dump_path(object_content, path_object)
+        object_load = edq.util.json.load_object_path(path_object, _TestConverter)
+
+        self.assertEqual(object_content, text_load)
+        self.assertEqual(object_load, text_load)
+
+class _TestConverter(edq.util.json.DictConverter):
+    def __init__(self, a: typing.Union[int, None] = None, b: typing.Union[str, None] = None, **kwargs) -> None:
+        self.a: typing.Union[int, None] = a
+        self.b: typing.Union[str, None] = b
+
+    def to_dict(self) -> typing.Dict[str, typing.Any]:
+        return vars(self)
+
+    @classmethod
+    def from_dict(cls, data: typing.Dict[str, typing.Any]) -> typing.Any:
+        return _TestConverter(**data)

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/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.2.dist-info → edq_utils-0.0.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edq-utils
-Version: 0.0.2
+Version: 0.0.4
 Summary: Common utilities used by EduLinq Python projects.
 Author-email: Eriq Augustine <eriq@edulinq.org>
 License: MIT License
@@ -37,6 +37,7 @@ 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.4.dist-info/RECORD

@@ -0,0 +1,41 @@
+edq/__init__.py,sha256=POoiN2MIpiTQijlzxyJCeYpx1EkkrGbcPzAy_Raps7A,86
+edq/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+edq/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+edq/cli/version.py,sha256=hEz8DonP6cmDMiNPpUT4V4hbSQhcC7z6NhJSxqVY6NY,592
+edq/cli/testing/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+edq/cli/testing/cli-test.py,sha256=1hjTnAjOKZu69yBBjsO4dn0m9ApF26luo2huSZr5_Yo,1048
+edq/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+edq/core/argparser.py,sha256=LWv4EYlgmqEw0jscpV_-aKSobBEDAZ02Zv3cF2JArx8,4180
+edq/core/argparser_test.py,sha256=YzNft7c1Nk5tQzHEW7nEuJakjvk1IZiYimaQ_6HI6Bo,4046
+edq/core/log.py,sha256=Aq5-Tznq5fgCfU0OI4ECy2OnCoiwV4bTFkhXXdLoG7Q,3726
+edq/core/version.py,sha256=cCadcn3M4qoxbQRu4WRHXUu_xl49GTGSDpr6hpr7Vxw,124
+edq/testing/__init__.py,sha256=IKd3fPU_8d_jP19HxG-zKwxFwn7nqFGGtXOY5slY41c,32
+edq/testing/asserts.py,sha256=kxNdAC3usbOBQXuagxUNv8IDQ57I3Moe4eWc51xaNIo,2524
+edq/testing/cli.py,sha256=u1GfgYz4_1oEKftCjrrg-gMQZpj_ry1hXvec2OQQA2M,9728
+edq/testing/cli_test.py,sha256=l-CPBXpiMb12_qgQj5FoXHM8GJBKnXieogrCb191Dlc,224
+edq/testing/run.py,sha256=qnqGCEwZP-hY87X99EJw2xoMaTF8QeOf7Lx8JI7oM_4,3843
+edq/testing/unittest.py,sha256=ysv_XTL14sDRf4EVx6lRN44A0InQSh-dYeG3bTJ9dzU,1751
+edq/testing/testdata/cli/tests/version_base.txt,sha256=5e9oSQaivA-0Th7wXpNRhACluyDwvFTL_1xfAkS2Pko,69
+edq/util/__init__.py,sha256=9EFKQE77S-B6OJJKFaMg8k3WkMMUQYlGjlTv6tQmWVo,29
+edq/util/dirent.py,sha256=YDgHW9xcYzid1rxsk3LowIBXW-JIokdN5SXaVSTFt4U,10334
+edq/util/dirent_test.py,sha256=oXpAaEhOkEr0zw0fdAPypx7QH1aFbY2Hpox-9OpZjhs,33380
+edq/util/json.py,sha256=IOTJqZGFYWgng7D1NMd6NDbbmOuw8C4Mpo6-2w1JFNY,5344
+edq/util/json_test.py,sha256=utUVRbw3z42ke4fpRVI294RrFHcMKms8khVYRkISNk4,8009
+edq/util/pyimport.py,sha256=26OIuCXELyqtwlooMqDEs4GJQrkrAgxnXNYTlqqtsBY,2852
+edq/util/pyimport_test.py,sha256=Xno0MIa3yMTfBfoTgjKCIMpr1ZShU6bvo9rBRdecXQU,4202
+edq/util/reflection.py,sha256=jPcW6h0fwSDYh04O5rUxlgoF7HK6fVQ2mq7DD9qPrEg,972
+edq/util/time.py,sha256=anoNM_KniARLombv2BnsoHuCzDqMKiDdIzV7RUe2ZOk,2648
+edq/util/time_test.py,sha256=iQZwzVTVQQ4TdXrLb9MUMCYlKrIe8qyF-hiC9YLTaMo,4610
+edq/util/testdata/dirent-operations/a.txt,sha256=h0KPxSKAPTEGXnvOPPA_5HUJZjHl4Hu9eg_eYMTPJcc,2
+edq/util/testdata/dirent-operations/file_empty,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+edq/util/testdata/dirent-operations/symlink_a.txt,sha256=h0KPxSKAPTEGXnvOPPA_5HUJZjHl4Hu9eg_eYMTPJcc,2
+edq/util/testdata/dirent-operations/symlink_file_empty,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+edq/util/testdata/dirent-operations/dir_1/b.txt,sha256=AmOCmYm2_ZVPcrqvL8ZLwuLwHWktTecphuqAj26ZgT8,2
+edq/util/testdata/dirent-operations/dir_1/dir_2/c.txt,sha256=o6XnFfDMV0pzw_m-u2vCTzL_1bZ7OHJEwskJ2neaFHg,2
+edq/util/testdata/dirent-operations/symlink_dir_1/b.txt,sha256=AmOCmYm2_ZVPcrqvL8ZLwuLwHWktTecphuqAj26ZgT8,2
+edq/util/testdata/dirent-operations/symlink_dir_1/dir_2/c.txt,sha256=o6XnFfDMV0pzw_m-u2vCTzL_1bZ7OHJEwskJ2neaFHg,2
+edq_utils-0.0.4.dist-info/licenses/LICENSE,sha256=MS4iYEl4rOxMoprZuc86iYVoyk4YgaVoMt7WmGvVF8w,1064
+edq_utils-0.0.4.dist-info/METADATA,sha256=Pt_CQ94UC8ePrD8iEFGSSltVQUJPh8h9-d3Pt_Ll1RE,2471
+edq_utils-0.0.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+edq_utils-0.0.4.dist-info/top_level.txt,sha256=znBHSj6tgXtcMKrUVtovLli5fIEJCb7d-BMxTLRK4zk,4
+edq_utils-0.0.4.dist-info/RECORD,,

edq_utils-0.0.2.dist-info/RECORD

@@ -1,26 +0,0 @@
-edq/__init__.py,sha256=miSsqPy2PFJ18TW9kocQJLcv4HFpkfQhcTzgAO-GTVE,22
-edq/testing/run.py,sha256=pibKFJDHCtGoKyuN7i95ZGjwuXV5jL-XPy4W-l14X2Q,3150
-edq/testing/unittest.py,sha256=WIcc5psTM-e6NQbQ3ajBjSRRRHBqvMuKOvK_pZMcTlk,1341
-edq/util/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-edq/util/dirent.py,sha256=LR-ePtQZKEWNfZkyJ-zxFdcggQKYZ8fT379mcBYeepw,9412
-edq/util/dirent_test.py,sha256=FSRqhp18S4-7J9XroLxPUoJMKPBDpp3PfPKraM_7atw,30037
-edq/util/json.py,sha256=YRUrQvLvwDTQBcURGk6nGJLd9m6TB_jdgdrYPLElcyk,2132
-edq/util/json_test.py,sha256=a0my-tdo1NoPv8wWwxk2pIw56CS7QyOrODkGx2-GO1c,4273
-edq/util/pyimport.py,sha256=M1j58vg4b6gTg92Cz5-bns3eQCCIMKDApBclP-iR620,2198
-edq/util/pyimport_test.py,sha256=wuTR5pzVZanWDA2FuVc-Pxyo_GwkGGfFf_qyK6LNQRs,2851
-edq/util/reflection.py,sha256=jPcW6h0fwSDYh04O5rUxlgoF7HK6fVQ2mq7DD9qPrEg,972
-edq/util/time.py,sha256=anoNM_KniARLombv2BnsoHuCzDqMKiDdIzV7RUe2ZOk,2648
-edq/util/time_test.py,sha256=iQZwzVTVQQ4TdXrLb9MUMCYlKrIe8qyF-hiC9YLTaMo,4610
-edq/util/testdata/dirent-operations/a.txt,sha256=h0KPxSKAPTEGXnvOPPA_5HUJZjHl4Hu9eg_eYMTPJcc,2
-edq/util/testdata/dirent-operations/file_empty,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-edq/util/testdata/dirent-operations/symlink_a.txt,sha256=h0KPxSKAPTEGXnvOPPA_5HUJZjHl4Hu9eg_eYMTPJcc,2
-edq/util/testdata/dirent-operations/symlink_file_empty,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-edq/util/testdata/dirent-operations/dir_1/b.txt,sha256=AmOCmYm2_ZVPcrqvL8ZLwuLwHWktTecphuqAj26ZgT8,2
-edq/util/testdata/dirent-operations/dir_1/dir_2/c.txt,sha256=o6XnFfDMV0pzw_m-u2vCTzL_1bZ7OHJEwskJ2neaFHg,2
-edq/util/testdata/dirent-operations/symlink_dir_1/b.txt,sha256=AmOCmYm2_ZVPcrqvL8ZLwuLwHWktTecphuqAj26ZgT8,2
-edq/util/testdata/dirent-operations/symlink_dir_1/dir_2/c.txt,sha256=o6XnFfDMV0pzw_m-u2vCTzL_1bZ7OHJEwskJ2neaFHg,2
-edq_utils-0.0.2.dist-info/licenses/LICENSE,sha256=MS4iYEl4rOxMoprZuc86iYVoyk4YgaVoMt7WmGvVF8w,1064
-edq_utils-0.0.2.dist-info/METADATA,sha256=WczGh7XL8QbJ0OLaLPE0WyHA65YucW8UAv0LG6TN7s8,2427
-edq_utils-0.0.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-edq_utils-0.0.2.dist-info/top_level.txt,sha256=znBHSj6tgXtcMKrUVtovLli5fIEJCb7d-BMxTLRK4zk,4
-edq_utils-0.0.2.dist-info/RECORD,,