Module wxversion

[frames | no frames]

## Module wxversion

If you have more than one version of wxPython installed this module allows your application to choose which version of wxPython will be imported when it does 'import wx'. The main function of this module is `select` and you use it like this:

    import wxversion
    wxversion.select('2.4')
    import wx

Or additional build options can also be selected, although they will not be required if they are not installed, like this:

    import wxversion
    wxversion.select('2.5.3-unicode')
    import wx

Or you can require an exact match on the build options like this:

    import wxversion
    wxversion.select('2.5.3-unicode', optionsRequired=True)
    import wx

Finally you can also specify a collection of versions that are allowed by your application, like this:

    import wxversion
    wxversion.select(['2.5.4', '2.5.5', '2.6'])
    import wx

Of course the default wxPython version can also be controlled by setting PYTHONPATH or by editing the wx.pth path configuration file, but using wxversion will allow an application to manage the version selection itself rather than depend on the user to setup the environment correctly.

It works by searching the sys.path for directories matching wx-* and then comparing them to what was passed to the select function. If a match is found then that path is inserted into sys.path.

NOTE: If you are making a 'bundle' of your application with a tool like py2exe then you should not use the wxversion module since it looks at the filesystem for the directories on sys.path, it will fail in a bundled environment. Instead you should simply ensure that the version of wxPython that you want is found by default on the sys.path when making the bundled version by setting PYTHONPATH. Then that version will be included in your bundle and your app will work as expected. Py2exe and the others usually have a way to tell at runtime if they are running from a bundle or running raw, so you can check that and only use wxversion if needed. For example, for py2exe:

    if not hasattr(sys, 'frozen'):
        import wxversion
        wxversion.select('2.5')
    import wx

More documentation on wxversion and multi-version installs can be found at: http://wiki.wxpython.org/index.cgi/MultiVersionInstalls

Exceptions
`VersionError` |

Function Summary
| ``checkInstalled`(versions, optionsRequired)` Check if there is a version of wxPython installed that matches one of the versions given.
| ``ensureMinimal`(minVersion, optionsRequired)` Checks to see if the default version of wxPython is greater-than or equal to `minVersion`.
| ``getInstalled`()` Returns a list of strings representing the installed wxPython versions that are found on the system.
| ``select`(versions, optionsRequired)` Search for a wxPython installation that matches version.

Variable Summary
`str` | `UPDATE_URL` = `'http://wxPython.org/'`

Function Details

### checkInstalled(versions, optionsRequired=False)

Check if there is a version of wxPython installed that matches one of the versions given. Returns True if so, False if not. This can be used to determine if calling `select` will succeed or not.

  Parameters:
    `versions` - Same as in `select`, either a string or a list of strings specifying the version(s) to check for.

    `optionsRequired` - Same as in `select`.

### ensureMinimal(minVersion, optionsRequired=False)

Checks to see if the default version of wxPython is greater-than or equal to `minVersion`. If not then it will try to find an installed version that is >= minVersion. If none are available then a message is displayed that will inform the user and will offer to open their web browser to the wxPython downloads page, and will then exit the application.

### getInstalled()

Returns a list of strings representing the installed wxPython versions that are found on the system.

### select(versions, optionsRequired=False)

Search for a wxPython installation that matches version. If one is found then sys.path is modified so that version will be imported with a 'import wx', otherwise a VersionError exception is raised. This funciton should only be caled once at the begining of the application before wxPython is imported.

  Parameters:
    `versions` - Specifies the version to look for, it can either be a string or a list of strings. Each string is compared to the installed wxPythons and the best match is inserted into the sys.path, allowing an 'import wx' to find that version.

    The version string is composed of the dotted version number (at least 2 of the 4 components) optionally followed by hyphen ('-') separated options (wx port, unicode/ansi, flavour, etc.) A match is determined by how much of the installed version matches what is given in the version parameter. If the version number components don't match then the score is zero, otherwise the score is increased for every specified optional component that is specified and that matches.

    Please note, however, that it is possible for a match to be selected that doesn't exactly match the versions requested. The only component that is required to be matched is the version number. If you need to require a match on the other components as well, then please use the optional `optionsRequired` parameter described next.

    `optionsRequired` - Allows you to specify that the other components of the version string (such as the port name or character type) are also required to be present for an installed version to be considered a match. Using this parameter allows you to change the selection from a soft, as close as possible match to a hard, exact match.

Variable Details

### UPDATE_URL

  Type:
    `str`
  Value:

        'http://wxPython.org/'

Generated by Epydoc 2.1.20050511.rpd on Thu Mar 22 12:08:40 2007 | http://epydoc.sf.net