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 _API
  44 from ._gi import Repository
  45 from ._gi import PyGIDeprecationWarning
  46 from ._gi import PyGIWarning
  47
  48 _API = _API  # pyflakes
  49 PyGIDeprecationWarning = PyGIDeprecationWarning
  50 PyGIWarning = PyGIWarning
  51
  52 _versions = {}
  53 _overridesdir = os.path.join(os.path.dirname(__file__), 'overrides')
  54
  55 # Needed for compatibility with "pygobject.h"/pygobject_init()
  56 _gobject = types.ModuleType("gi._gobject")
  57 sys.modules[_gobject.__name__] = _gobject
  58 _gobject._PyGObject_API = _gi._PyGObject_API
  59 _gobject.pygobject_version = _gi.pygobject_version
  60
  61 version_info = _gi.pygobject_version[:]
  62 __version__ = "{0}.{1}.{2}".format(*version_info)
  63
  64
  65 class _DummyStaticModule(types.ModuleType):
  66     __path__ = None
  67
  68     def __getattr__(self, name):
  69         raise AttributeError(_static_binding_error)
  70
  71
  72 sys.modules['glib'] = _DummyStaticModule('glib', _static_binding_error)
  73 sys.modules['gobject'] = _DummyStaticModule('gobject', _static_binding_error)
  74 sys.modules['gio'] = _DummyStaticModule('gio', _static_binding_error)
  75 sys.modules['gtk'] = _DummyStaticModule('gtk', _static_binding_error)
  76 sys.modules['gtk.gdk'] = _DummyStaticModule('gtk.gdk', _static_binding_error)
  77
  78
  79 def check_version(version):
  80     if isinstance(version, str):
  81         version_list = tuple(map(int, version.split(".")))
  82     else:
  83         version_list = version
  84
  85     if version_list > version_info:
  86         raise ValueError((
  87             "pygobject's version %s required, and available version "
  88             "%s is not recent enough") % (version, __version__)
  89         )
  90
  91
  92 def require_version(namespace, version):
  93     """ Ensures the correct versions are loaded when importing `gi` modules.
  94
  95     :param namespace: The name of module to require.
  96     :type namespace: str
  97     :param version: The version of module to require.
  98     :type version: str
  99     :raises ValueError: If module/version is already loaded, already required, or unavailable.
 100
 101     :Example:
 102
 103     .. code-block:: python
 104
 105         import gi
 106         gi.require_version('Gtk', '3.0')
 107
 108     """
 109     repository = Repository.get_default()
 110
 111     if sys.version_info[0] <= 2:
 112         if not isinstance(version, basestring):
 113             raise ValueError('Namespace version needs to be a string.')
 114     else:
 115         if not isinstance(version, str):
 116             raise ValueError('Namespace version needs to be a string.')
 117
 118     if namespace in repository.get_loaded_namespaces():
 119         loaded_version = repository.get_version(namespace)
 120         if loaded_version != version:
 121             raise ValueError('Namespace %s is already loaded with version %s' %
 122                              (namespace, loaded_version))
 123
 124     if namespace in _versions and _versions[namespace] != version:
 125         raise ValueError('Namespace %s already requires version %s' %
 126                          (namespace, _versions[namespace]))
 127
 128     available_versions = repository.enumerate_versions(namespace)
 129     if not available_versions:
 130         raise ValueError('Namespace %s not available' % namespace)
 131
 132     if version not in available_versions:
 133         raise ValueError('Namespace %s not available for version %s' %
 134                          (namespace, version))
 135
 136     _versions[namespace] = version
 137
 138
 139 def require_versions(requires):
 140     """ Utility function for consolidating multiple `gi.require_version()` calls.
 141
 142     :param requires: The names and versions of modules to require.
 143     :type requires: dict
 144
 145     :Example:
 146
 147     .. code-block:: python
 148
 149         import gi
 150         gi.require_versions({'Gtk': '3.0', 'GLib': '2.0', 'Gio': '2.0'})
 151     """
 152     for module_name, module_version in requires.items():
 153         require_version(module_name, module_version)
 154
 155
 156 def get_required_version(namespace):
 157     return _versions.get(namespace, None)
 158
 159
 160 def require_foreign(namespace, symbol=None):
 161     """Ensure the given foreign marshaling module is available and loaded.
 162
 163     :param str namespace:
 164         Introspection namespace of the foreign module (e.g. "cairo")
 165     :param symbol:
 166         Optional symbol typename to ensure a converter exists.
 167     :type symbol: str or None
 168     :raises: ImportError
 169
 170     :Example:
 171
 172     .. code-block:: python
 173
 174         import gi
 175         import cairo
 176         gi.require_foreign('cairo')
 177
 178     """
 179     try:
 180         _gi.require_foreign(namespace, symbol)
 181     except Exception as e:
 182         raise ImportError(str(e))
 183     importlib.import_module('gi.repository', namespace)