edq-utils 0.1.9__py3-none-any.whl

edq/util/parse.py

@@ -0,0 +1,33 @@
+import typing
+
+BOOL_TRUE_STRINGS: typing.Set[str] = {
+    'true', 't',
+    'yes', 'y',
+    '1',
+}
+
+BOOL_FALSE_STRINGS: typing.Set[str] = {
+    'false', 'f',
+    'no', 'n',
+    '0',
+}
+
+def boolean(raw_text: typing.Union[str, bool]) -> bool:
+    """
+    Parse a boolean from a string using common string representations for true/false.
+    This function assumes the entire string is the boolean (not just a part of it).
+    If the string is not true or false, then raise an exception.
+    """
+
+    if (isinstance(raw_text, bool)):
+        return raw_text
+
+    text = str(raw_text).lower().strip()
+
+    if (text in BOOL_TRUE_STRINGS):
+        return True
+
+    if (text in BOOL_FALSE_STRINGS):
+        return False
+
+    raise ValueError(f"Could not convert text to boolean: '{raw_text}'.")

edq/util/pyimport.py

@@ -0,0 +1,94 @@
+import importlib
+import importlib.util
+import os
+import typing
+import uuid
+
+import edq.util.dirent
+
+_import_cache: typing.Dict[str, typing.Any] = {}
+""" A cache to help avoid importing a module multiple times. """
+
+def import_path(raw_path: str, cache: bool = True, module_name: typing.Union[str, None] = None) -> typing.Any:
+    """
+    Import a module from a file.
+    If cache is false, then the module will not be fetched or stored in this module's cache.
+    """
+
+    path = os.path.abspath(raw_path)
+    cache_key = f"PATH::{path}"
+
+    # Check the cache before importing.
+    if (cache):
+        module = _import_cache.get(cache_key, None)
+        if (module is not None):
+            return module
+
+    if (not edq.util.dirent.exists(path)):
+        raise ValueError(f"Module path does not exist: '{raw_path}'.")
+
+    if (not os.path.isfile(path)):
+        raise ValueError(f"Module path is not a file: '{raw_path}'.")
+
+    if (module_name is None):
+        module_name = str(uuid.uuid4()).replace('-', '')
+
+    spec = importlib.util.spec_from_file_location(module_name, path)
+    if ((spec is None) or (spec.loader is None)):
+        raise ValueError(f"Failed to load module specification for path: '{raw_path}'.")
+
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+
+    # Store the module in the cache.
+    if (cache):
+        _import_cache[cache_key] = module
+
+    return module
+
+def import_name(module_name: str, cache: bool = True) -> typing.Any:
+    """
+    Import a module from a name.
+    The module must already be in the system's path (sys.path).
+    If cache is false, then the module will not be fetched or stored in this module's cache.
+    """
+
+    cache_key = f"NAME::{module_name}"
+
+    # Check the cache before importing.
+    if (cache):
+        module = _import_cache.get(cache_key, None)
+        if (module is not None):
+            return module
+
+    try:
+        module = importlib.import_module(module_name)
+    except ImportError as ex:
+        raise ValueError(f"Unable to locate module '{module_name}'.") from ex
+
+    # Store the module in the cache.
+    if (cache):
+        _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

@@ -0,0 +1,119 @@
+import os
+
+import edq.testing.unittest
+import edq.util.pyimport
+
+THIS_DIR = os.path.abspath(os.path.dirname(os.path.realpath(__file__)))
+PACKAGE_ROOT_DIR = os.path.join(THIS_DIR, '..')
+
+class TestPyImport(edq.testing.unittest.BaseTest):
+    """ Test Python importing operations. """
+
+    def test_import_path_base(self):
+        """ Test importing a module from a path. """
+
+        # [(relative path, error substring), ...]
+        # All paths are relative to the package root.
+        test_cases = [
+            # Standard Module
+            (os.path.join('util', 'pyimport.py'), None),
+
+            # Errors
+            ('ZZZ', 'Module path does not exist'),
+            ('util', 'Module path is not a file'),
+        ]
+
+        for (i, test_case) in enumerate(test_cases):
+            (relpath, error_substring) = test_case
+
+            with self.subTest(msg = f"Case {i} ('{relpath}'):"):
+                path = os.path.join(PACKAGE_ROOT_DIR, relpath)
+
+                try:
+                    module = edq.util.pyimport.import_path(path)
+                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(module)
+
+    def test_import_name_base(self):
+        """ Test importing a module from a name. """
+
+        # [(name, error substring), ...]
+        test_cases = [
+            # Standard Module
+            ('edq.util.pyimport', None),
+
+            # Package (__init__.py)
+            ('edq.util', None),
+
+            # Errors
+            ('', 'Empty module name'),
+            ('edq.util.ZZZ', 'Unable to locate module'),
+            ('edq.util.pyimport.ZZZ', 'Unable to locate module'),
+        ]
+
+        for (i, test_case) in enumerate(test_cases):
+            (name, error_substring) = test_case
+
+            with self.subTest(msg = f"Case {i} ('{name}'):"):
+                try:
+                    module = edq.util.pyimport.import_name(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(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/util/reflection.py

@@ -0,0 +1,32 @@
+import typing
+
+def get_qualified_name(target: typing.Union[type, object, str]) -> str:
+    """
+    Try to get a qualified name for a type (or for the type of an object).
+    Names will not always come out clean.
+    """
+
+    # Get the type for this target.
+    if (isinstance(target, type)):
+        target_class = target
+    elif (callable(target)):
+        target_class = typing.cast(type, target)
+    else:
+        target_class = type(target)
+
+    # Check for various name components.
+    parts = []
+
+    if (hasattr(target_class, '__module__')):
+        parts.append(str(getattr(target_class, '__module__')))
+
+    if (hasattr(target_class, '__qualname__')):
+        parts.append(str(getattr(target_class, '__qualname__')))
+    elif (hasattr(target_class, '__name__')):
+        parts.append(str(getattr(target_class, '__name__')))
+
+    # Fall back to just the string reprsentation.
+    if (len(parts) == 0):
+        return str(target_class)
+
+    return '.'.join(parts)

edq/util/time.py

@@ -0,0 +1,75 @@
+import datetime
+import time
+
+PRETTY_SHORT_FORMAT: str = '%Y-%m-%d %H:%M'
+
+class Duration(int):
+    """
+    A Duration represents some length in time in milliseconds.
+    """
+
+    def to_secs(self) -> float:
+        """ Convert the duration to float seconds. """
+
+        return self / 1000.0
+
+    def to_msecs(self) -> int:
+        """ Convert the duration to integer milliseconds. """
+
+        return self
+
+class Timestamp(int):
+    """
+    A Timestamp represent a moment in time (sometimes called "datetimes").
+    Timestamps are internally represented by the number of milliseconds since the
+    (Unix Epoch)[https://en.wikipedia.org/wiki/Unix_time].
+    This is sometimes referred to as "Unix Time".
+    Since Unix Time is in UTC, timestamps do not need to carry timestamp information with them.
+
+    Note that timestamps are just integers with some decoration,
+    so they respond to all normal int functionality.
+    """
+
+    def sub(self, other: 'Timestamp') -> Duration:
+        """ Return a new duration that is the difference of this and the given duration. """
+
+        return Duration(self - other)
+
+    def to_pytime(self, timezone: datetime.timezone = datetime.timezone.utc) -> datetime.datetime:
+        """ Convert this timestamp to a Python datetime in the given timezone (UTC by default). """
+
+        return datetime.datetime.fromtimestamp(self / 1000, timezone)
+
+    def to_local_pytime(self) -> datetime.datetime:
+        """ Convert this timestamp to a Python datetime in the system timezone. """
+
+        local_timezone = datetime.datetime.now().astimezone().tzinfo
+        if ((local_timezone is None) or (not isinstance(local_timezone, datetime.timezone))):
+            raise ValueError("Could not discover local timezone.")
+
+        return self.to_pytime(timezone = local_timezone)
+
+    def pretty(self, short: bool = False, timezone: datetime.timezone = datetime.timezone.utc) -> str:
+        """
+        Get a "pretty" string representation of this timestamp.
+        There is no guarantee that this representation can be parsed back to its original form.
+        """
+
+        pytime = self.to_pytime(timezone = timezone)
+
+        if (short):
+            return pytime.strftime(PRETTY_SHORT_FORMAT)
+
+        return pytime.isoformat(timespec = 'milliseconds')
+
+    @staticmethod
+    def from_pytime(pytime: datetime.datetime) -> 'Timestamp':
+        """ Convert a Python datetime to a timestamp. """
+
+        return Timestamp(int(pytime.timestamp() * 1000))
+
+    @staticmethod
+    def now() -> 'Timestamp':
+        """ Get a Timestamp that represents the current moment. """
+
+        return Timestamp(time.time() * 1000)

edq/util/time_test.py

@@ -0,0 +1,107 @@
+import time
+import datetime
+
+import edq.testing.unittest
+import edq.util.time
+
+TIMEZONE_UTC: datetime.timezone = datetime.timezone.utc
+TIMEZONE_PST: datetime.timezone = datetime.timezone(datetime.timedelta(hours = -7), name = 'PST')
+TIMEZONE_CEST: datetime.timezone = datetime.timezone(datetime.timedelta(hours = 2), name = 'CEST')
+
+class TestTime(edq.testing.unittest.BaseTest):
+    """ Test time-based operations. """
+
+    def test_timestamp_now(self):
+        """ Test getting a timestamp for the current moment. """
+
+        start = edq.util.time.Timestamp.now()
+        time.sleep(0.01)
+        middle = edq.util.time.Timestamp.now()
+        time.sleep(0.01)
+        end = edq.util.time.Timestamp.now()
+
+        self.assertLessEqual(start, middle)
+        self.assertLessEqual(middle, end)
+
+    def test_timestamp_pytime_conversion(self):
+        """ Test converting between timestamps and Python datetimes. """
+
+        # [(timestamp, python time), ...]
+        test_cases = [
+            (edq.util.time.Timestamp(0), datetime.datetime(1970, 1, 1, 0, 0, 0, 0, TIMEZONE_UTC)),
+
+            (edq.util.time.Timestamp(1755139534019), datetime.datetime(2025, 8, 14, 2,  45, 34, 19000, TIMEZONE_UTC)),
+            (edq.util.time.Timestamp(1755139534019), datetime.datetime(2025, 8, 13, 19, 45, 34, 19000, TIMEZONE_PST)),
+            (edq.util.time.Timestamp(1755139534019), datetime.datetime(2025, 8, 14, 4,  45, 34, 19000, TIMEZONE_CEST)),
+        ]
+
+        for (i, test_case) in enumerate(test_cases):
+            (timestamp, pytime) = test_case
+
+            with self.subTest(msg = f"Case {i} ('{timestamp}' == '{pytime}'):"):
+                convert_pytime = timestamp.to_pytime(pytime.tzinfo)
+                self.assertEqual(pytime, convert_pytime, 'pytime')
+
+                convert_timestamp = edq.util.time.Timestamp.from_pytime(pytime)
+                self.assertEqual(timestamp, convert_timestamp, 'timestamp')
+
+                # Check other time zones.
+                # Use string comparisons to ensure the timezone is compared (and not just the UTC time).
+                timezones = [
+                    TIMEZONE_UTC,
+                    TIMEZONE_PST,
+                    TIMEZONE_CEST,
+                ]
+
+                for timezone in timezones:
+                    pytime_pst = pytime.astimezone(timezone).isoformat(timespec = 'milliseconds')
+                    convert_pytime_pst = timestamp.to_pytime(timezone).isoformat(timespec = 'milliseconds')
+                    self.assertEqual(pytime_pst, convert_pytime_pst, f"pytime {timezone}")
+
+    def test_timestamp_pretty(self):
+        """ Test the "pretty" representations of timestamps. """
+
+        # [(timestamp, timezone, pretty short, pretty long), ...]
+        test_cases = [
+            (edq.util.time.Timestamp(0), TIMEZONE_UTC, "1970-01-01 00:00", "1970-01-01T00:00:00.000+00:00"),
+
+            (edq.util.time.Timestamp(1755139534019), TIMEZONE_UTC,  "2025-08-14 02:45", "2025-08-14T02:45:34.019+00:00"),
+            (edq.util.time.Timestamp(1755139534019), TIMEZONE_PST,  "2025-08-13 19:45", "2025-08-13T19:45:34.019-07:00"),
+            (edq.util.time.Timestamp(1755139534019), TIMEZONE_CEST, "2025-08-14 04:45", "2025-08-14T04:45:34.019+02:00"),
+        ]
+
+        for (i, test_case) in enumerate(test_cases):
+            (timestamp, timezone, expected_pretty_short, expected_pretty_long) = test_case
+
+            with self.subTest(msg = f"Case {i} ('{timestamp}'):"):
+                actual_pretty_short = timestamp.pretty(short = True, timezone = timezone)
+                actual_pretty_long = timestamp.pretty(short = False, timezone = timezone)
+
+                self.assertEqual(expected_pretty_short, actual_pretty_short, 'short')
+                self.assertEqual(expected_pretty_long, actual_pretty_long, 'long')
+
+    def test_timestamp_sub(self):
+        """ Test subtracting timestamps. """
+
+        # [(a, b, expected), ...]
+        # All values in this structure will be in ints and converted later.
+        test_cases = [
+            (0, 0, 0),
+            (0, 1, -1),
+            (1, 0, 1),
+
+            (100, 100, 0),
+            (100, 101, -1),
+            (101, 100, 1),
+        ]
+
+        for (i, test_case) in enumerate(test_cases):
+            (raw_a, raw_b, raw_expected) = test_case
+
+            with self.subTest(msg = f"Case {i} ({raw_a} - {raw_b}):"):
+                a = edq.util.time.Timestamp(raw_a)
+                b = edq.util.time.Timestamp(raw_b)
+                expected = edq.util.time.Duration(raw_expected)
+
+                actual = a - b
+                self.assertEqual(expected, actual)

edq_utils-0.1.9.dist-info/METADATA

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: edq-utils
+Version: 0.1.9
+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
+Requires-Dist: platformdirs
+Requires-Dist: requests
+Requires-Dist: requests-toolbelt
+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"
+Dynamic: license-file
+
+# EduLinq Python Utilities
+
+Common utilities used by EduLinq Python projects.
+
+Links:
+ - [API Reference](https://edulinq.github.io/python-utils)
+ - [Installation / Requirements](#installation--requirements)
+ - [Configuration System](#configuration-system)
+   - [Configuration Sources](#configuration-sources)
+
+## 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. |