python-module-utils 1.0.0__py3-none-any.whl

module_utils/__init__.py

@@ -0,0 +1,42 @@
+__all__ = (
+           "ImportResultMode",
+           "ModulePlaceholder",
+           "extended_import",
+           "extended_from_import",
+           "optional_import",
+           "optional_from_import"
+          )
+
+
+
+
+from ._importing import *
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+#Copyright © 2026 Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
+#
+#
+#This program is free software: you can redistribute it and/or modify it under
+#the terms of the GNU General Public License as published by the Free Software
+#Foundation, either version 3 of the License, or (at your option) any later
+#version.
+#This program is distributed in the hope that it will be useful, but WITHOUT ANY
+#WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+#PARTICULAR PURPOSE.
+#See the GNU General Public License for more details.
+#You should have received a copy of the GNU General Public License along with
+#this program. If not, see <https://www.gnu.org/licenses/>.

module_utils/_importing.py

@@ -0,0 +1,289 @@
+__all__ = (
+           "ImportResultMode",
+           "ModulePlaceholder",
+           "extended_import",
+           "extended_from_import",
+           "optional_import",
+           "optional_from_import"
+          )
+
+
+
+
+import sys
+import importlib
+import enum
+import itertools
+from types import SimpleNamespace
+from functools import wraps
+
+
+
+
+
+
+
+
+class ImportResultMode(enum.StrEnum):
+    OBJECTS_STATUSES__FLAT_ROWS_TUPLE = enum.auto()
+    OBJECTS_STATUSES__FLAT_ROWS_LIST = enum.auto()
+    OBJECTS_STATUSES__FLAT_COLUMNS_TUPLE = enum.auto()
+    OBJECTS_STATUSES__FLAT_COLUMNS_LIST = enum.auto()
+    OBJECTS_STATUSES__ROWS_TUPLE = enum.auto()
+    OBJECTS_STATUSES__ROWS_LIST = enum.auto()
+    OBJECTS_STATUSES__COLUMNS_TUPLE = enum.auto()
+    OBJECTS_STATUSES__COLUMNS_LIST = enum.auto()
+    OBJECTS_ONLY__TUPLE_OR_OBJECT = enum.auto()
+    OBJECTS_ONLY__LIST_OR_OBJECT = enum.auto()
+    OBJECTS_ONLY__TUPLE = enum.auto()
+    OBJECTS_ONLY__LIST = enum.auto()
+
+
+
+
+class ModulePlaceholder(SimpleNamespace):
+    def __getattr__(self, name):
+        #don’t create attributes with system-defined (“dunder”) names
+        if len(name) >= 5  and  name.startswith("__")  and  name.endswith("__"):
+            raise AttributeError(name, self)
+        
+        new_attribute = ModulePlaceholder()
+        setattr(self, name, new_attribute)
+        
+        return new_attribute
+    
+    
+    
+    
+    def __bool__(self):
+        return False
+
+
+
+
+def extended_import(modules, *, ignored_exceptions_on_import=None, import_object_on_failure=None, get_top_level_modules=False, exception_on_failure_to_get_top_level_modules=True, result_mode=ImportResultMode.OBJECTS_STATUSES__FLAT_ROWS_TUPLE):
+    #prepare parameters
+    if isinstance(modules, str):
+        modules = (modules, )
+    if ignored_exceptions_on_import is None:
+        ignored_exceptions_on_import = ()
+    elif isinstance(ignored_exceptions_on_import, type)  and  issubclass(ignored_exceptions_on_import, BaseException):
+        ignored_exceptions_on_import = (ignored_exceptions_on_import, )
+    elif not isinstance(ignored_exceptions_on_import, tuple):
+        ignored_exceptions_on_import = tuple(ignored_exceptions_on_import)
+    
+    
+    import_objects = []
+    import_statuses = []
+    
+    
+    #import the modules
+    for m in modules:
+        #disallow relative module names
+        if m.startswith("."):
+            raise ValueError("Relative module names are not allowed.")
+        
+        if get_top_level_modules:
+            try:
+                module_object = importlib.__import__(m)
+            except ignored_exceptions_on_import:
+                top_level_module = m.partition(".")[0]
+                
+                top_level_module_imported = False
+                if m != top_level_module:
+                    #the module is not a top-level module:
+                    
+                    #explicitly import the top-level module
+                    try:
+                        module_object = importlib.__import__(top_level_module)
+                    except Exception as e:
+                        if exception_on_failure_to_get_top_level_modules:
+                            raise ImportError(f"Failed to explicitly import the top-level module `{top_level_module}`, which was tried as a consequence of the “ignored” failure to import the module `{m}`.") from e
+                    else:
+                        top_level_module_imported = True
+                
+                if not top_level_module_imported:
+                    if callable(import_object_on_failure):
+                        module_object = import_object_on_failure()
+                    else:
+                        module_object = import_object_on_failure
+                
+                success = False
+            else:
+                success = True
+        else:
+            try:
+                module_object = importlib.import_module(m)
+            except ignored_exceptions_on_import:
+                if callable(import_object_on_failure):
+                    module_object = import_object_on_failure()
+                else:
+                    module_object = import_object_on_failure
+                
+                success = False
+            else:
+                success = True
+        
+        import_objects.append(module_object)
+        import_statuses.append(success)
+    
+    
+    return _render_import_result(import_objects, import_statuses, result_mode=result_mode)
+
+
+
+
+def extended_from_import(module, attributes, *, package=None, ignored_exceptions_on_import=None, ignore_non_existent_attributes_on_import=False, import_object_on_failure=None, result_mode=ImportResultMode.OBJECTS_STATUSES__FLAT_ROWS_TUPLE):
+    #prepare parameters
+    if isinstance(attributes, str):
+        attributes = (attributes, )
+    if ignored_exceptions_on_import is None:
+        ignored_exceptions_on_import = ()
+    elif isinstance(ignored_exceptions_on_import, type)  and  issubclass(ignored_exceptions_on_import, BaseException):
+        ignored_exceptions_on_import = (ignored_exceptions_on_import, )
+    elif not isinstance(ignored_exceptions_on_import, tuple):
+        ignored_exceptions_on_import = tuple(ignored_exceptions_on_import)
+    
+    #validate parameters
+    if len(attributes) == 0:
+        raise ValueError("Not at least one attribute name given.")
+    if package is None:
+        if module.startswith("."):
+            raise ValueError("Relative module name but no package name given.")
+    else:
+        if not module.startswith("."):
+            raise ValueError("Absolute module name but a package name given.")
+    
+    
+    #resolve a relative to an absolute module name
+    module = importlib.util.resolve_name(module, package)
+    
+    
+    import_objects = []
+    import_statuses = []
+    
+    
+    #import the module
+    try:
+        module_object = importlib.__import__(module, fromlist=attributes)
+    except ignored_exceptions_on_import:
+        if callable(import_object_on_failure):
+            import_objects.extend([import_object_on_failure()  for _ in attributes])
+        else:
+            import_objects.extend( [import_object_on_failure] * len(attributes) )
+        
+        import_statuses.extend( [False] * len(attributes) )
+    else:
+        #get the attributes
+        for a in attributes:
+            #disallow importing the `*`-special-attribute
+            if a == "*":
+                raise ValueError("Importing the `*`-special-attribute is not allowed.")
+            
+            try:
+                attribute_object = getattr(module_object, a)
+            except AttributeError:
+                if not ignore_non_existent_attributes_on_import:
+                    raise
+                
+                if callable(import_object_on_failure):
+                    attribute_object = import_object_on_failure()
+                else:
+                    attribute_object = import_object_on_failure
+                
+                success = False
+            else:
+                success = True
+            
+            import_objects.append(attribute_object)
+            import_statuses.append(success)
+    
+    
+    return _render_import_result(import_objects, import_statuses, result_mode=result_mode)
+
+
+
+
+@wraps(extended_import)
+def optional_import(*args, ignored_exceptions_on_import=(ImportError, ), import_object_on_failure=ModulePlaceholder, exception_on_failure_to_get_top_level_modules=False, **kwargs):
+    return extended_import(*args, ignored_exceptions_on_import=ignored_exceptions_on_import, import_object_on_failure=import_object_on_failure, exception_on_failure_to_get_top_level_modules=exception_on_failure_to_get_top_level_modules, **kwargs)
+
+
+
+
+@wraps(extended_from_import)
+def optional_from_import(*args, ignored_exceptions_on_import=(ImportError, ), ignore_non_existent_attributes_on_import=True, import_object_on_failure=ModulePlaceholder, **kwargs):
+    return extended_from_import(*args, ignored_exceptions_on_import=ignored_exceptions_on_import, ignore_non_existent_attributes_on_import=ignore_non_existent_attributes_on_import, import_object_on_failure=import_object_on_failure, **kwargs)
+
+
+
+
+def _render_import_result(import_objects, import_statuses, *, result_mode):
+    match result_mode:
+        case ImportResultMode.OBJECTS_STATUSES__FLAT_ROWS_TUPLE:
+            return tuple(itertools.chain.from_iterable(zip(import_objects, import_statuses, strict=True)))
+        case ImportResultMode.OBJECTS_STATUSES__FLAT_ROWS_LIST:
+            return list(itertools.chain.from_iterable(zip(import_objects, import_statuses, strict=True)))
+        case ImportResultMode.OBJECTS_STATUSES__FLAT_COLUMNS_TUPLE:
+            return tuple(import_objects + import_statuses)
+        case ImportResultMode.OBJECTS_STATUSES__FLAT_COLUMNS_LIST:
+            return import_objects + import_statuses
+        case ImportResultMode.OBJECTS_STATUSES__ROWS_TUPLE:
+            return tuple(zip(import_objects, import_statuses, strict=True))
+        case ImportResultMode.OBJECTS_STATUSES__ROWS_LIST:
+            return [ list(row)  for row in zip(import_objects, import_statuses, strict=True) ]
+        case ImportResultMode.OBJECTS_STATUSES__COLUMNS_TUPLE:
+            return ( tuple(import_objects), tuple(import_statuses) )
+        case ImportResultMode.OBJECTS_STATUSES__COLUMNS_LIST:
+            return [import_objects, import_statuses]
+        case ImportResultMode.OBJECTS_ONLY__TUPLE_OR_OBJECT:
+            match len(import_objects):
+                case 0:
+                    return None
+                case 1:
+                    return import_objects[0]
+                case _:
+                    return tuple(import_objects)
+        case ImportResultMode.OBJECTS_ONLY__LIST_OR_OBJECT:
+            match len(import_objects):
+                case 0:
+                    return None
+                case 1:
+                    return import_objects[0]
+                case _:
+                    return import_objects
+        case ImportResultMode.OBJECTS_ONLY__TUPLE:
+            return tuple(import_objects)
+        case ImportResultMode.OBJECTS_ONLY__LIST:
+            return import_objects
+        case _:
+            raise NotImplementedError(f"Unknown return mode `{result_mode.name  if isinstance(result_mode, enum.Enum)  else  result_mode}`.")
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+#Copyright © 2026 Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
+#
+#
+#This program is free software: you can redistribute it and/or modify it under
+#the terms of the GNU General Public License as published by the Free Software
+#Foundation, either version 3 of the License, or (at your option) any later
+#version.
+#This program is distributed in the hope that it will be useful, but WITHOUT ANY
+#WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+#PARTICULAR PURPOSE.
+#See the GNU General Public License for more details.
+#You should have received a copy of the GNU General Public License along with
+#this program. If not, see <https://www.gnu.org/licenses/>.

python_module_utils-1.0.0.dist-info/METADATA

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: python-module-utils
+Version: 1.0.0
+Summary: Utilities for handling Python modules.
+Author-email: Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
+Maintainer-email: Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
+Project-URL: website, https://gitlab.com/calestyo/python-module-utils
+Keywords: modules,module,import,importing
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Natural Language :: English
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+License-File: LICENCE
+Dynamic: license-file

python_module_utils-1.0.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+module_utils/__init__.py,sha256=Kvp7-rDjdscPD7mErfeEg1cMa5WNVRkoE9DcIrE_de4,966
+module_utils/_importing.py,sha256=DqPCM4v2IqW84fUQiG6Wsr8Yzeu4cX0rG3LK9ZuOtgw,11000
+python_module_utils-1.0.0.dist-info/licenses/LICENCE,sha256=PU9RjoB0SBo6BuxWcNT0qhUaxxzhDBS9k156jzTDhNE,691
+python_module_utils-1.0.0.dist-info/METADATA,sha256=UelOnWJuSsBrZnYcYxaYhyPfj2EaGVPqlnDGQY14ZHw,695
+python_module_utils-1.0.0.dist-info/WHEEL,sha256=lTU6B6eIfYoiQJTZNc-fyaR6BpL6ehTzU3xGYxn2n8k,91
+python_module_utils-1.0.0.dist-info/top_level.txt,sha256=_7C3dmxpcDNCi2vJovqg0nbJgyUUhDO7xWyYbx36H84,13
+python_module_utils-1.0.0.dist-info/RECORD,,

python_module_utils-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (78.1.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

python_module_utils-1.0.0.dist-info/licenses/LICENCE

@@ -0,0 +1,13 @@
+Copyright © 2026 Christoph Anton Mitterer <mail@christoph.anton.mitterer.name>
+
+
+This program is free software: you can redistribute it and/or modify it under
+the terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later
+version.
+This program is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE.
+See the GNU General Public License for more details.
+You should have received a copy of the GNU General Public License along with
+this program. If not, see <https://www.gnu.org/licenses/>.

python_module_utils-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+module_utils