wxPython/wxversion/wxversion.py

   1 #----------------------------------------------------------------------
   2 # Name:        wxversion
   3 # Purpose:     Allows a wxPython program to search for alternate
   4 #              installations of the wxPython packages and modify sys.path
   5 #              so they will be found when "import wx" is done.
   6 #
   7 # Author:      Robin Dunn
   8 #
   9 # Created:     24-Sept-2004
  10 # RCS-ID:      $Id$
  11 # Copyright:   (c) 2004 by Total Control Software
  12 # Licence:     wxWindows license
  13 #----------------------------------------------------------------------
  14
  15 """
  16 If you have more than one version of wxPython installed this module
  17 allows your application to choose which version of wxPython will be
  18 imported when it does 'import wx'.  You use it like this::
  19
  20     import wxversion
  21     wxversion.select('2.4')
  22     import wx
  23
  24 Or additional build options can also be selected, like this::
  25
  26     import wxversion
  27     wxversion.select('2.5.3-unicode')
  28     import wx
  29
  30 Of course the default wxPython version can also be controlled by
  31 setting PYTHONPATH or by editing the wx.pth path configuration file,
  32 but using wxversion will allow an application to manage the version
  33 selection itself rather than depend on the user to setup the
  34 environment correctly.
  35
  36 It works by searching the sys.path for directories matching wx-* and
  37 then comparing them to what was passed to the select function.  If a
  38 match is found then that path is inserted into sys.path.
  39
  40 NOTE: If you are making a 'bundle' of your application with a tool
  41 like py2exe then you should *not* use the wxversion module since it
  42 looks at the filesystem for the directories on sys.path, it will fail
  43 in a bundled environment.  Instead you should simply ensure that the
  44 version of wxPython that you want is found by default on the sys.path
  45 when making the bundled version by setting PYTHONPATH.  Then that
  46 version will be included in your bundle and your app will work as
  47 expected.  Py2exe and the others usually have a way to tell at runtime
  48 if they are running from a bundle or running raw, so you can check
  49 that and only use wxversion if needed.  For example, for py2exe::
  50
  51     if not hasattr(sys, 'frozen'):
  52         import wxversion
  53         wxversion.select('2.5')
  54     import wx
  55
  56 More documentation on wxversion and multi-version installs can be
  57 found at: http://wiki.wxpython.org/index.cgi/MultiVersionInstalls
  58
  59 """
  60
  61 import sys, os, glob, fnmatch
  62
  63
  64 _selected = None
  65 class VersionError(Exception):
  66     pass
  67
  68 #----------------------------------------------------------------------
  69
  70 def select(versions):
  71     """
  72     Search for a wxPython installation that matches version.  If one
  73     is found then sys.path is modified so that version will be
  74     imported with a 'import wx', otherwise a VersionError exception is
  75     raised.  This funciton should only be caled once at the begining
  76     of the application before wxPython is imported.
  77
  78         :param version: Specifies the version to look for, it can
  79                         either be a string or a list of strings.  Each
  80                         string is compared to the installed wxPythons
  81                         and the best match is inserted into the
  82                         sys.path, allowing an 'import wx' to find that
  83                         version.
  84
  85                         The version string is composed of the dotted
  86                         version number (at least 2 of the 4 components)
  87                         optionally followed by hyphen ('-') separated
  88                         options (wx port, unicode/ansi, flavour, etc.)  A
  89                         match is determined by how much of the installed
  90                         version matches what is given in the version
  91                         parameter.  If the version number components don't
  92                         match then the score is zero, otherwise the score
  93                         is increased for every specified optional component
  94                         that is specified and that matches.
  95     """
  96     if type(versions) == str:
  97         versions = [versions]
  98
  99     global _selected
 100     if _selected is not None:
 101         # A version was previously selected, ensure that it matches
 102         # this new request
 103         for ver in versions:
 104             if _selected.Score(_wxPackageInfo(ver)) > 0:
 105                 return
 106         # otherwise, raise an exception
 107         raise VersionError("A previously selected wx version does not match the new request.")
 108
 109     # If we get here then this is the first time wxversion is used,
 110     # ensure that wxPython hasn't been imported yet.
 111     if sys.modules.has_key('wx') or sys.modules.has_key('wxPython'):
 112         raise VersionError("wxversion.select() must be called before wxPython is imported")
 113
 114     # Look for a matching version and manipulate the sys.path as
 115     # needed to allow it to be imported.
 116     installed = _find_installed(True)
 117     bestMatch = _get_best_match(installed, versions)
 118
 119     if bestMatch is None:
 120         raise VersionError("Requested version of wxPython not found")
 121
 122     sys.path.insert(0, bestMatch.pathname)
 123     _selected = bestMatch
 124
 125 #----------------------------------------------------------------------
 126
 127 UPDATE_URL = "http://wxPython.org/"
 128 #UPDATE_URL = "http://sourceforge.net/project/showfiles.php?group_id=10718"
 129
 130
 131 def ensureMinimal(minVersion):
 132     """
 133     Checks to see if the default version of wxPython is greater-than
 134     or equal to `minVersion`.  If not then it will try to find an
 135     installed version that is >= minVersion.  If none are available
 136     then a message is displayed that will inform the user and will
 137     offer to open their web browser to the wxPython downloads page,
 138     and will then exit the application.
 139     """
 140     assert type(minVersion) == str
 141
 142     # ensure that wxPython hasn't been imported yet.
 143     if sys.modules.has_key('wx') or sys.modules.has_key('wxPython'):
 144         raise VersionError("wxversion.ensureMinimal() must be called before wxPython is imported")
 145
 146     bestMatch = None
 147     minv = _wxPackageInfo(minVersion)
 148     defaultPath = _find_default()
 149     if defaultPath:
 150         defv = _wxPackageInfo(defaultPath, True)
 151         if defv >= minv:
 152             bestMatch = defv
 153
 154     if bestMatch is None:
 155         installed = _find_installed()
 156         if installed:
 157             # The list is in reverse sorted order, so if the first one is
 158             # big enough then choose it
 159             if installed[0] >= minv:
 160                 bestMatch = installed[0]
 161
 162     if bestMatch is None:
 163         import wx, webbrowser
 164         versions = "\n".join(["      "+ver for ver in getInstalled()])
 165         app = wx.PySimpleApp()
 166         result = wx.MessageBox("This application requires a version of wxPython "
 167                                "greater than or equal to %s, but a matching version "
 168                                "was not found.\n\n"
 169                                "You currently have these version(s) installed:\n%s\n\n"
 170                                "Would you like to download a new version of wxPython?\n"
 171                                % (minVersion, versions),
 172                       "wxPython Upgrade Needed", style=wx.YES_NO)
 173         if result == wx.YES:
 174             webbrowser.open(UPDATE_URL)
 175         app.MainLoop()
 176         sys.exit()
 177
 178     sys.path.insert(0, bestMatch.pathname)
 179     global _selected
 180     _selected = bestMatch
 181
 182
 183 #----------------------------------------------------------------------
 184
 185 def checkInstalled(versions):
 186     """
 187     Check if there is a version of wxPython installed that matches one
 188     of the versions given.  Returns True if so, False if not.  This
 189     can be used to determine if calling `select` will succeed or not.
 190
 191         :param version: Same as in `select`, either a string or a list
 192                         of strings specifying the version(s) to check
 193                         for.
 194     """
 195
 196     if type(versions) == str:
 197         versions = [versions]
 198     installed = _find_installed()
 199     bestMatch = _get_best_match(installed, versions)
 200     return bestMatch is not None
 201
 202 #----------------------------------------------------------------------
 203
 204 def getInstalled():
 205     """
 206     Returns a list of strings representing the installed wxPython
 207     versions that are found on the system.
 208     """
 209     installed = _find_installed()
 210     return [os.path.basename(p.pathname)[3:] for p in installed]
 211
 212
 213
 214 #----------------------------------------------------------------------
 215 # private helpers...
 216
 217 def _get_best_match(installed, versions):
 218     bestMatch = None
 219     bestScore = 0
 220     for pkg in installed:
 221         for ver in versions:
 222             score = pkg.Score(_wxPackageInfo(ver))
 223             if score > bestScore:
 224                 bestMatch = pkg
 225                 bestScore = score
 226     return bestMatch
 227
 228
 229 _pattern = "wx-[0-9].*"
 230 def _find_installed(removeExisting=False):
 231     installed = []
 232     toRemove = []
 233     for pth in sys.path:
 234
 235         # empty means to look in the current dir
 236         if not pth:
 237             pth = '.'
 238
 239         # skip it if it's not a package dir
 240         if not os.path.isdir(pth):
 241             continue
 242
 243         base = os.path.basename(pth)
 244
 245         # if it's a wx path that's already in the sys.path then mark
 246         # it for removal and then skip it
 247         if fnmatch.fnmatchcase(base, _pattern):
 248             toRemove.append(pth)
 249             continue
 250
 251         # now look in the dir for matching subdirs
 252         for name in glob.glob(os.path.join(pth, _pattern)):
 253             # make sure it's a directory
 254             if not os.path.isdir(name):
 255                 continue
 256             # and has a wx subdir
 257             if not os.path.exists(os.path.join(name, 'wx')):
 258                 continue
 259             installed.append(_wxPackageInfo(name, True))
 260
 261     if removeExisting:
 262         for rem in toRemove:
 263             del sys.path[sys.path.index(rem)]
 264
 265     installed.sort()
 266     installed.reverse()
 267     return installed
 268
 269
 270 # Scan the sys.path looking for either a directory matching _pattern,
 271 # or a wx.pth file
 272 def _find_default():
 273     for pth in sys.path:
 274         # empty means to look in the current dir
 275         if not pth:
 276             pth = '.'
 277
 278         # skip it if it's not a package dir
 279         if not os.path.isdir(pth):
 280             continue
 281
 282         # does it match the pattern?
 283         base = os.path.basename(pth)
 284         if fnmatch.fnmatchcase(base, _pattern):
 285             return pth
 286
 287     for pth in sys.path:
 288         if not pth:
 289             pth = '.'
 290         if not os.path.isdir(pth):
 291             continue
 292         if os.path.exists(os.path.join(pth, 'wx.pth')):
 293             base = open(os.path.join(pth, 'wx.pth')).read()
 294             return os.path.join(pth, base)
 295
 296     return None
 297
 298
 299 class _wxPackageInfo(object):
 300     def __init__(self, pathname, stripFirst=False):
 301         self.pathname = pathname
 302         base = os.path.basename(pathname)
 303         segments = base.split('-')
 304         if stripFirst:
 305             segments = segments[1:]
 306         self.version = tuple([int(x) for x in segments[0].split('.')])
 307         self.options = segments[1:]
 308
 309
 310     def Score(self, other):
 311         score = 0
 312
 313         # whatever number of version components given in other must
 314         # match exactly
 315         minlen = min(len(self.version), len(other.version))
 316         if self.version[:minlen] != other.version[:minlen]:
 317             return 0
 318         score += 1
 319
 320         for opt in other.options:
 321             if opt in self.options:
 322                 score += 1
 323         return score
 324
 325
 326
 327     def __lt__(self, other):
 328         return self.version < other.version or \
 329                (self.version == other.version and self.options < other.options)
 330     def __le__(self, other):
 331         return self.version <= other.version or \
 332                (self.version == other.version and self.options <= other.options)
 333
 334     def __gt__(self, other):
 335         return self.version > other.version or \
 336                (self.version == other.version and self.options > other.options)
 337     def __ge__(self, other):
 338         return self.version >= other.version or \
 339                (self.version == other.version and self.options >= other.options)
 340
 341     def __eq__(self, other):
 342         return self.version == other.version and self.options == other.options
 343
 344
 345
 346 #----------------------------------------------------------------------
 347
 348 if __name__ == '__main__':
 349     import pprint
 350
 351     #ensureMinimal('2.5')
 352     #pprint.pprint(sys.path)
 353     #sys.exit()
 354
 355
 356     def test(version):
 357         # setup
 358         savepath = sys.path[:]
 359
 360         #test
 361         select(version)
 362         print "Asked for %s:\t got: %s" % (version, sys.path[0])
 363         pprint.pprint(sys.path)
 364         print
 365
 366         # reset
 367         sys.path = savepath[:]
 368         global _selected
 369         _selected = None
 370
 371
 372     # make some test dirs
 373     names = ['wx-2.4',
 374              'wx-2.5.2',
 375              'wx-2.5.2.9-gtk2-unicode',
 376              'wx-2.5.2.9-gtk-ansi',
 377              'wx-2.5.1',
 378              'wx-2.5.2.8-gtk2-unicode',
 379              'wx-2.5.3']
 380     for name in names:
 381         d = os.path.join('/tmp', name)
 382         os.mkdir(d)
 383         os.mkdir(os.path.join(d, 'wx'))
 384
 385     # setup sys.path to see those dirs
 386     sys.path.append('/tmp')
 387
 388
 389     # now run some tests
 390     pprint.pprint( getInstalled())
 391     print checkInstalled("2.4")
 392     print checkInstalled("2.5-unicode")
 393     print checkInstalled("2.99-bogus")
 394     print "Current sys.path:"
 395     pprint.pprint(sys.path)
 396     print
 397
 398     test("2.4")
 399     test("2.5")
 400     test("2.5-gtk2")
 401     test("2.5.2")
 402     test("2.5-ansi")
 403     test("2.5-unicode")
 404
 405     # There isn't a unicode match for this one, but it will give the best
 406     # available 2.4.  Should it give an error instead?  I don't think so...
 407     test("2.4-unicode")
 408
 409     # Try asking for multiple versions
 410     test(["2.6", "2.5.3", "2.5.2-gtk2"])
 411
 412     try:
 413         # expecting an error on this one
 414         test("2.6")
 415     except VersionError, e:
 416         print "Asked for 2.6:\t got Exception:", e
 417
 418     # check for exception when incompatible versions are requested
 419     try:
 420         select("2.4")
 421         select("2.5")
 422     except VersionError, e:
 423         print "Asked for incompatible versions, got Exception:", e
 424
 425     # cleanup
 426     for name in names:
 427         d = os.path.join('/tmp', name)
 428         os.rmdir(os.path.join(d, 'wx'))
 429         os.rmdir(d)
 430
 431