gi/__init__.py

   1 # -*- Mode: Python; py-indent-offset: 4 -*-
   2 # vim: tabstop=4 shiftwidth=4 expandtab
   3 #
   4 # Copyright (C) 2005-2009 Johan Dahlin <johan@gnome.org>
   5 #
   6 # This library is free software; you can redistribute it and/or
   7 # modify it under the terms of the GNU Lesser General Public
   8 # License as published by the Free Software Foundation; either
   9 # version 2.1 of the License, or (at your option) any later version.
  10 #
  11 # This library is distributed in the hope that it will be useful,
  12 # but WITHOUT ANY WARRANTY; without even the implied warranty of
  13 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 # Lesser General Public License for more details.
  15 #
  16 # You should have received a copy of the GNU Lesser General Public
  17 # License along with this library; if not, write to the Free Software
  18 # Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301
  19 # USA
  20
  21 from __future__ import absolute_import
  22
  23 # support overrides in different directories than our gi module
  24 from pkgutil import extend_path
  25 __path__ = extend_path(__path__, __name__)
  26
  27 import sys
  28 import os
  29 import importlib
  30 import types
  31
  32 _static_binding_error = ('When using gi.repository you must not import static '
  33                          'modules like "gobject". Please change all occurrences '
  34                          'of "import gobject" to "from gi.repository import GObject". '
  35                          'See: https://bugzilla.gnome.org/show_bug.cgi?id=709183')
  36
  37 # we can't have pygobject 2 loaded at the same time we load the internal _gobject
  38 if 'gobject' in sys.modules:
  39     raise ImportError(_static_binding_error)
  40
  41
  42 from . import _gi
  43 from ._gi import _gobject
  44 from ._gi import _API
  45 from ._gi import Repository
  46 from ._gi import PyGIDeprecationWarning
  47 from ._gi import PyGIWarning
  48
  49 _API = _API  # pyflakes
  50 PyGIDeprecationWarning = PyGIDeprecationWarning
  51 PyGIWarning = PyGIWarning
  52
  53 _versions = {}
  54 _overridesdir = os.path.join(os.path.dirname(__file__), 'overrides')
  55
  56 version_info = _gobject.pygobject_version[:]
  57 __version__ = "{0}.{1}.{2}".format(*version_info)
  58
  59
  60 class _DummyStaticModule(types.ModuleType):
  61     __path__ = None
  62
  63     def __getattr__(self, name):
  64         raise AttributeError(_static_binding_error)
  65
  66
  67 sys.modules['glib'] = _DummyStaticModule('glib', _static_binding_error)
  68 sys.modules['gobject'] = _DummyStaticModule('gobject', _static_binding_error)
  69 sys.modules['gio'] = _DummyStaticModule('gio', _static_binding_error)
  70 sys.modules['gtk'] = _DummyStaticModule('gtk', _static_binding_error)
  71 sys.modules['gtk.gdk'] = _DummyStaticModule('gtk.gdk', _static_binding_error)
  72
  73
  74 def check_version(version):
  75     if isinstance(version, str):
  76         version_list = tuple(map(int, version.split(".")))
  77     else:
  78         version_list = version
  79
  80     if version_list > version_info:
  81         raise ValueError((
  82             "pygobject's version %s required, and available version "
  83             "%s is not recent enough") % (version, __version__)
  84         )
  85
  86
  87 def require_version(namespace, version):
  88     """ Ensures the correct versions are loaded when importing `gi` modules.
  89
  90     :param namespace: The name of module to require.
  91     :type namespace: str
  92     :param version: The version of module to require.
  93     :type version: str
  94     :raises ValueError: If module/version is already loaded, already required, or unavailable.
  95
  96     :Example:
  97
  98     .. code-block:: python
  99
 100         import gi
 101         gi.require_version('Gtk', '3.0')
 102
 103     """
 104     repository = Repository.get_default()
 105
 106     if namespace in repository.get_loaded_namespaces():
 107         loaded_version = repository.get_version(namespace)
 108         if loaded_version != version:
 109             raise ValueError('Namespace %s is already loaded with version %s' %
 110                              (namespace, loaded_version))
 111
 112     if namespace in _versions and _versions[namespace] != version:
 113         raise ValueError('Namespace %s already requires version %s' %
 114                          (namespace, _versions[namespace]))
 115
 116     available_versions = repository.enumerate_versions(namespace)
 117     if not available_versions:
 118         raise ValueError('Namespace %s not available' % namespace)
 119
 120     if version not in available_versions:
 121         raise ValueError('Namespace %s not available for version %s' %
 122                          (namespace, version))
 123
 124     _versions[namespace] = version
 125
 126
 127 def require_versions(requires):
 128     """ Utility function for consolidating multiple `gi.require_version()` calls.
 129
 130     :param requires: The names and versions of modules to require.
 131     :type requires: dict
 132
 133     :Example:
 134
 135     .. code-block:: python
 136
 137         import gi
 138         gi.require_versions({'Gtk': '3.0', 'GLib': '2.0', 'Gio': '2.0'})
 139     """
 140     for module_name, module_version in requires.items():
 141         require_version(module_name, module_version)
 142
 143
 144 def get_required_version(namespace):
 145     return _versions.get(namespace, None)
 146
 147
 148 def require_foreign(namespace, symbol=None):
 149     """Ensure the given foreign marshaling module is available and loaded.
 150
 151     :param str namespace:
 152         Introspection namespace of the foreign module (e.g. "cairo")
 153     :param symbol:
 154         Optional symbol typename to ensure a converter exists.
 155     :type symbol: str or None
 156     :raises: ImportError
 157
 158     :Example:
 159
 160     .. code-block:: python
 161
 162         import gi
 163         import cairo
 164         gi.require_foreign('cairo')
 165
 166     """
 167     try:
 168         _gi.require_foreign(namespace, symbol)
 169     except Exception as e:
 170         raise ImportError(str(e))
 171     importlib.import_module('gi.repository', namespace)