gi: Add require_versions() function

Adds a new function that accepts a dict of one or more namespace, version
pairs through which it iterates and calls `gi.require_version()`
for each pair. Also adds a test for the new function.

https://bugzilla.gnome.org/show_bug.cgi?id=761141

2 files changed, 39 insertions, 0 deletions

diff --git a/gi/__init__.py b/gi/__init__.py
index caad5694..1b139c6f 100644
--- a/gi/__init__.py
+++ b/gi/__init__.py
@@ -85,6 +85,22 @@ def check_version(version):
 
 
 def require_version(namespace, version):
+    """ Ensures the correct versions are loaded when importing `gi` modules.
+
+    :param namespace: The name of module to require.
+    :type namespace: str
+    :param version: The version of module to require.
+    :type version: str
+    :raises ValueError: If module/version is already loaded, already required, or unavailable.
+
+    :Example:
+
+    .. code-block:: python
+
+        import gi
+        gi.require_version('Gtk', '3.0')
+
+    """
     repository = Repository.get_default()
 
     if namespace in repository.get_loaded_namespaces():
@@ -108,6 +124,23 @@ def require_version(namespace, version):
     _versions[namespace] = version
 
 
+def require_versions(requires):
+    """ Utility function for consolidating multiple `gi.require_version()` calls.
+
+    :param requires: The names and versions of modules to require.
+    :type requires: dict
+
+    :Example:
+
+    .. code-block:: python
+
+        import gi
+        gi.require_versions({'Gtk': '3.0', 'GLib': '2.0', 'Gio': '2.0'})
+    """
+    for module_name, module_version in requires.items():
+        require_version(module_name, module_version)
+
+
 def get_required_version(namespace):
     return _versions.get(namespace, None)
 
diff --git a/tests/test_import_machinery.py b/tests/test_import_machinery.py
index ad1f3305..8cc37cb5 100644
--- a/tests/test_import_machinery.py
+++ b/tests/test_import_machinery.py
@@ -145,6 +145,12 @@ class TestImporter(unittest.TestCase):
                 from gi.repository import InvalidGObjectRepositoryModuleName
                 InvalidGObjectRepositoryModuleName
 
+    def test_require_versions(self):
+        import gi
+        gi.require_versions({'GLib': '2.0', 'Gio': '2.0', 'GObject': '2.0'})
+        from gi.repository import GLib
+        GLib
+
     def test_get_import_stacklevel(self):
         gi.importer.get_import_stacklevel(import_hook=True)
         gi.importer.get_import_stacklevel(import_hook=False)