edq-utils 0.0.1__tar.gz

edq_utils-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+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.

edq_utils-0.0.1/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: edq-utils
+Version: 0.0.1
+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
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.1; 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.
+
+## 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 .
+```

edq_utils-0.0.1/README.md

@@ -0,0 +1,18 @@
+# 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 .
+```

edq_utils-0.0.1/edq/__init__.py

@@ -0,0 +1 @@
+__version__ = '0.0.1'

edq_utils-0.0.1/edq/util/dirent.py

@@ -0,0 +1,154 @@
+import atexit
+import os
+import shutil
+import tempfile
+import uuid
+
+DEAULT_ENCODING: str = 'utf-8'
+""" The default encoding that will be used when reading and writing. """
+
+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 os.path.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(path: str) -> None:
+    """
+    Make a directory (including any required parent directories).
+    Does not complain if the directory (or parents) already exist.
+    """
+
+    os.makedirs(path, exist_ok = True)
+
+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 os.path.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 move(source: str, dest: str) -> None:
+    """
+    Move the source dirent to the given destination.
+    Any existing destination will be removed before moving.
+    """
+
+    # 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 (os.path.exists(dest) and os.path.samefile(source, dest)):
+        return
+
+    # Create any required parents.
+    os.makedirs(os.path.dirname(dest), exist_ok = True)
+
+    # Remove any existing dest.
+    if (os.path.exists(dest)):
+        remove(dest)
+
+    shutil.move(source, dest)
+
+def copy(source: str, dest: str, dirs_exist_ok: bool = False) -> None:
+    """
+    Copy a file or directory into dest.
+    If source is a file, then dest can be a file or dir.
+    If source is a dir, it is copied as a subdirectory of dest.
+    If dirs_exist_ok is true, an existing destination directory is allowed.
+    """
+
+    if (os.path.isfile(source) or os.path.islink(source)):
+        os.makedirs(os.path.dirname(dest), exist_ok = True)
+
+        try:
+            shutil.copy2(source, dest, follow_symlinks = False)
+        except shutil.SameFileError:
+            return
+    else:
+        if (os.path.isdir(dest)):
+            dest = os.path.join(dest, os.path.basename(source))
+
+        shutil.copytree(source, dest, dirs_exist_ok = dirs_exist_ok, symlinks = True)
+
+def copy_contents(source: str, dest: str) -> None:
+    """
+    Copy a file or the contents of a directory (excluding the top-level directory) into dest.
+    For a file: `cp source dest/`
+    For a dir: `cp -r source/* dest/`
+    """
+
+    source = os.path.abspath(source)
+
+    if (os.path.isfile(source)):
+        copy(source, dest)
+        return
+
+    for dirent in os.listdir(source):
+        source_path = os.path.join(source, dirent)
+        dest_path = os.path.join(dest, dirent)
+
+        if (os.path.isfile(source_path) or os.path.islink(source_path)):
+            copy(source_path, dest_path)
+        else:
+            shutil.copytree(source_path, dest_path, symlinks = True)
+
+def read_file(path: str, strip: bool = True, encoding: str = DEAULT_ENCODING) -> str:
+    """ Read the contents of a file. """
+
+    with open(path, 'r', encoding = encoding) as file:
+        contents = file.read()
+
+    if (strip):
+        contents = contents.strip()
+
+    return contents
+
+def write_file(path: str, contents: str, strip: bool = True, newline: bool = True, encoding: str = DEAULT_ENCODING) -> None:
+    """
+    Write the contents of a file.
+    Any existing file will be truncated.
+    """
+
+    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)

edq_utils-0.0.1/edq/util/dirent_test.py

@@ -0,0 +1,170 @@
+import os
+import sys
+import unittest
+
+import edq.util.dirent
+
+THIS_DIR = os.path.abspath(os.path.dirname(os.path.realpath(__file__)))
+TEST_BASE_DIR = os.path.join(THIS_DIR, 'testdata', 'dirent-operations')
+"""
+This test data directory is laid out as:
+.
+├── a.txt
+├── dir_1
+│   ├── b.txt
+│   └── dir_2
+│       └── c.txt
+├── dir_empty
+├── file_empty
+├── symlinklink_a.txt -> a.txt
+├── symlinklink_dir_1 -> dir_1
+└── symlinklink_dir_empty -> dir_empty
+
+Where non-empty files are filled with their filename (without the extension).
+dir_empty will not exist in the repository (since it is an empty directory),
+but it will be created by _prep_temp_dir().
+"""
+
+DIRENT_TYPE_DIR = 'dir'
+DIRENT_TYPE_FILE = 'file'
+
+class TestDirentOperations(unittest.TestCase):
+    """ Test basic operations on dirents. """
+
+    @unittest.skipIf((sys.platform.startswith("win") and (sys.version_info > (3, 11))), "windows symlink behavior")
+    def test_dirent_base(self):
+        """ Test that the base temp directory is properly setup. """
+
+        temp_dir = self._prep_temp_dir()
+
+        expected_paths = [
+            ('a.txt', DIRENT_TYPE_FILE),
+            ('dir_1', DIRENT_TYPE_DIR),
+            (os.path.join('dir_1', 'b.txt'), DIRENT_TYPE_FILE),
+            (os.path.join('dir_1', 'dir_2'), DIRENT_TYPE_DIR),
+            (os.path.join('dir_1', 'dir_2', 'c.txt'), DIRENT_TYPE_FILE),
+            ('dir_empty', DIRENT_TYPE_DIR),
+            ('file_empty', DIRENT_TYPE_FILE),
+            ('symlinklink_a.txt', DIRENT_TYPE_FILE, True),
+            ('symlinklink_dir_1', DIRENT_TYPE_DIR, True),
+            ('symlinklink_dir_empty', DIRENT_TYPE_DIR, True),
+        ]
+
+        self._check_existing_paths(temp_dir, expected_paths)
+
+    def test_dirent_operations_remove(self):
+        """ Test removing dirents. """
+
+        temp_dir = self._prep_temp_dir()
+
+        # Remove these paths in this order.
+        remove_relpaths = [
+            # Symlink - File
+            'symlinklink_a.txt',
+
+            # Symlink - Dir
+            'symlinklink_dir_1',
+
+            # File in Directory
+            os.path.join('dir_1', 'dir_2', 'c.txt'),
+
+            # File
+            'a.txt',
+
+            # Empty File
+            'file_empty'
+
+            # Directory
+            'dir_1',
+
+            # Empty Directory
+            'dir_empty'
+
+            # Non-Existent
+            'ZZZ'
+        ]
+
+        expected_paths = [
+            (os.path.join('dir_1', 'dir_2'), DIRENT_TYPE_DIR),
+            ('file_empty', DIRENT_TYPE_FILE),
+            # Windows has some symlink issues, so we will not check for this file.
+            # ('symlinklink_dir_empty', DIRENT_TYPE_DIR, True),
+        ]
+
+        for relpath in remove_relpaths:
+            path = os.path.join(temp_dir, relpath)
+            edq.util.dirent.remove(path)
+
+        self._check_nonexisting_paths(temp_dir, remove_relpaths)
+        self._check_existing_paths(temp_dir, expected_paths)
+
+    def _prep_temp_dir(self):
+        temp_dir = edq.util.dirent.get_temp_dir(prefix = 'edq_test_dirent_')
+        edq.util.dirent.mkdir(os.path.join(temp_dir, 'dir_empty'))
+        edq.util.dirent.copy_contents(TEST_BASE_DIR, temp_dir)
+        return temp_dir
+
+    def _check_existing_paths(self, base_dir, raw_paths):
+        """
+        Ensure that specific paths exists, and fail the test if they do not.
+        All paths should be relative to the base dir.
+        Paths can be:
+         - A string.
+         - A two-item tuple (path, dirent type).
+         - A three-item tuple (path, dirent type, is link?).
+        Missing components are not defaulted, they are just not checked.
+        """
+
+        for raw_path in raw_paths:
+            relpath = ''
+            dirent_type = None
+            is_link = None
+
+            if (isinstance(raw_path, str)):
+                relpath = raw_path
+            elif (isinstance(raw_path, tuple)):
+                if (len(raw_path) not in [2, 3]):
+                    raise ValueError(f"Expected exactly two or three items for path check, found {len(raw_path)} items: '{raw_path}'.")
+
+                relpath = raw_path[0]
+                dirent_type = raw_path[1]
+
+                if (len(raw_path) == 3):
+                    is_link = raw_path[2]
+            else:
+                raise ValueError(f"Could not parse expected path ({type(raw_path)}): '{raw_path}'.")
+
+            path = os.path.join(base_dir, relpath)
+
+            # Check the path exists.
+            if (not os.path.exists(path)):
+                self.fail(f"Expected path does not exist: '{relpath}'.")
+
+            # Check the type of the dirent.
+            if (dirent_type is not None):
+                if (dirent_type == DIRENT_TYPE_DIR):
+                    if (not os.path.isdir(path)):
+                        self.fail(f"Expected path to be a directory, but it is not: '{relpath}'.")
+                elif (dirent_type == DIRENT_TYPE_FILE):
+                    if (not os.path.isfile(path)):
+                        self.fail(f"Expected path to be a file, but it is not: '{relpath}'.")
+                else:
+                    raise ValueError(f"Unknown dirent type '{dirent_type}' for path: '{relpath}'.")
+
+            # Check the link status.
+            if (is_link is not None):
+                if (is_link != os.path.islink(path)):
+                    self.fail(f"Expected path does not have a matching link status. Expected {is_link}, but is {not is_link}: '{relpath}'.")
+
+    def _check_nonexisting_paths(self, base_dir, raw_paths):
+        """
+        Ensure that specific paths do not exists, and fail the test if they do exist.
+        All paths should be relative to the base dir.
+        Unlike _check_existing_paths(), paths should only be strings.
+        """
+
+        for relpath in raw_paths:
+            path = os.path.join(base_dir, relpath)
+
+            if (os.path.exists(path)):
+                self.fail(f"Path exists when it should not: '{relpath}'.")

edq_utils-0.0.1/edq/util/testdata/dirent-operations/a.txt

@@ -0,0 +1 @@
+a

edq_utils-0.0.1/edq/util/testdata/dirent-operations/dir_1/b.txt

@@ -0,0 +1 @@
+b

edq_utils-0.0.1/edq/util/testdata/dirent-operations/dir_1/dir_2/c.txt

@@ -0,0 +1 @@
+c

edq_utils-0.0.1/edq/util/testdata/dirent-operations/symlinklink_a.txt

@@ -0,0 +1 @@
+a

edq_utils-0.0.1/edq/util/testdata/dirent-operations/symlinklink_dir_1/b.txt

@@ -0,0 +1 @@
+b

edq_utils-0.0.1/edq/util/testdata/dirent-operations/symlinklink_dir_1/dir_2/c.txt

@@ -0,0 +1 @@
+c

edq_utils-0.0.1/edq_utils.egg-info/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: edq-utils
+Version: 0.0.1
+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
+Provides-Extra: dev
+Requires-Dist: mypy>=1.14.1; 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.
+
+## 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 .
+```

edq_utils-0.0.1/edq_utils.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+requirements-dev.txt
+requirements.txt
+edq/__init__.py
+edq/util/__init__.py
+edq/util/dirent.py
+edq/util/dirent_test.py
+edq/util/testdata/dirent-operations/a.txt
+edq/util/testdata/dirent-operations/file_empty
+edq/util/testdata/dirent-operations/symlinklink_a.txt
+edq/util/testdata/dirent-operations/dir_1/b.txt
+edq/util/testdata/dirent-operations/dir_1/dir_2/c.txt
+edq/util/testdata/dirent-operations/symlinklink_dir_1/b.txt
+edq/util/testdata/dirent-operations/symlinklink_dir_1/dir_2/c.txt
+edq_utils.egg-info/PKG-INFO
+edq_utils.egg-info/SOURCES.txt
+edq_utils.egg-info/dependency_links.txt
+edq_utils.egg-info/requires.txt
+edq_utils.egg-info/top_level.txt

edq_utils-0.0.1/edq_utils.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

edq_utils-0.0.1/edq_utils.egg-info/requires.txt

@@ -0,0 +1,6 @@
+
+[dev]
+mypy>=1.14.1
+pylint
+twine
+vermin

edq_utils-0.0.1/edq_utils.egg-info/top_level.txt

@@ -0,0 +1 @@
+edq

edq_utils-0.0.1/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+build-backend = "setuptools.build_meta"
+requires = [
+    "setuptools",
+    "packaging>=21.3",
+    "twine",
+    "vermin",
+]
+
+[project]
+name = "edq-utils"
+description = "Common utilities used by EduLinq Python projects."
+readme = "README.md"
+requires-python = ">=3.8"
+license = {file = "LICENSE"}
+
+authors = [
+    {name = "Eriq Augustine", email = "eriq@edulinq.org"},
+]
+
+keywords = ['education', 'utilities']
+classifiers = [
+    'Intended Audience :: Developers',
+    'License :: OSI Approved :: MIT License',
+    'Programming Language :: Python :: 3.8',
+]
+
+dynamic = [
+    "version",
+    "dependencies",
+    "optional-dependencies",
+]
+
+[tool.setuptools.dynamic]
+version = {attr = "edq.__version__"}
+dependencies = {file = ["requirements.txt"]}
+optional-dependencies = {dev = {file = ["requirements-dev.txt"]}}
+
+[project.urls]
+Homepage = "https://github.com/edulinq/python-utils"
+Repository = "https://github.com/edulinq/python-utils"
+
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.package-data]
+"*" = ["*"]
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["edq*"]

edq_utils-0.0.1/requirements-dev.txt

@@ -0,0 +1,4 @@
+mypy>=1.14.1
+pylint
+twine
+vermin

edq_utils-0.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+