wxPython 4.0.3 Released

"The show must go on."

wxPython 4.0.3 is now available at PyPI, with some additional files at the Extras archive.

This is another quick turn-around release in order to solve a couple semi-serious issues found in 4.0.2. Changes in this release include the following:

  • Fixed a linking problem on macOS. The new waf added an explicit link to the Python shared library which meant that it would try to load it at runtime, even if a different Python (such as Anaconda, EDM or Homebrew) was used to import wxPython. This, of course, caused runtime errors. (#892)

  • Sort pages by dock_pos when added to automatic (agw.aui) notebook. (#882)

  • Fix a bug in py.introspect.getTokens. (#889)

  • Added Vagrant configuration for Fedora-28. Removed Fedora-23 (#884)

  • Added wrappers for the wx.WindowIDRef class and added the wx.NewIdRef function. These will make it possible to create reserved Window IDs using the same mechanism which is used when passing wx.ID_ANY to a widget constructor. The object returned by wx.NewIdRef will automatically convert to an int when passing it to a window constructor, and can also be used as the source in a Bind(). (#896)

  • Fixed issue when sys.prefix is not unicode (Python2) and when its contents are not translatable to utf-8.

Avoiding Window IDs

Due to some changes upstream in wxWidgets the wxNewId function has been deprecated. This deprecation first took effect in wxPython in the recent 4.0.2 release, and has triggered some discussions about window IDs in the wxPython-users group. This post will give a little more context and background, and also list some examples and advice I gave in wxPython-users so it can be more easily found than just being buried in a message archive.

Background

About 20 years ago wxWidgets was rearchitected to use event tables to dispatch events to event handlers. Prior to this change when events arrived in the application they handled by calling the C++ virtual method intended to handle that kind of event. In other words, C++'s virtual method dispatch mechanism handled it. This worked well, but it was very inflexible and cumbersome. Switching to event tables simplified many things, increased the flexibility, and made it easier to add new kinds of events to the library as needed without redesigning base classes, etc.

The items in the event tables consisted of an event type ID, the source widget ID, a pointer to the member function to be called when the event arrives, and some additional housekeeping items. Originally the tables were all constructed at compile time and are a member of the class whose members are the event handler methods. Since they are built at compile-time then these tables are static (unchangeable) at runtime. A little later on dynamic event tables were added and that allowed wxPython to be born, but even then it was a very long time before it was common practice for wxWidgets C++ program to use dynamic event tables to any great extent.

Since the event tables were defined statically at compile time that meant that the table items which needed window IDs to properly route the event would also need to have the ID defined at compile time as well. That led to the common practice for wxWidgets users to create a bunch of ID_FOO constants and manually managing their values and worrying about whether there were overlaps between sets of IDs. This works fine, but can be cumbersome at times.

In the early days of wxPython it quickly became obvious that following the same C++ patterns was not a very fun way to work with the library. Once wxWidgets adopted the practice that widgets would generate their own ID if -1 or wxID_ANY was passed to the constructor then several Python-only enhancements naturally fell into place as well, such as the wx.PyEventBinder objects and the wx.EvtHandler.Bind method. I'll show some of the ways that wxPython can be used without IDs in the next section.

Writing ID-free wxPython

There are a few things that have been done to minimize the need to have preallocated IDs in wxPython. In fact, back in the early days of this project there were a number of advocates for eliminating, or at least hiding the ID parameters throughout all of the wxPython API. The reasoning was that they aren't really necessary in most cases, and the remaining cases could likely be worked around easily. When you boil it all down to the nitty-gritty, the primary purpose of window IDs is for identifying the source of events when searching for matching handlers, but there are many cases where it simply doesn't matter.

  1. Many consider it more pythonic to Bind() an event handler directly to the widget that produces the event, such as binding EVT_BUTTON to the button object itself. In this case, the button's ID does not matter since there can only be one source of button events seen at that point in the hierarchy. So the following works and no specific IDs need to be dealt with at all:

    obj = SomeWidget(self, wx.ID_ANY, ...)
    obj.Bind(wx.EVT_SOMETHING, self.myHandler)
    
  2. Building on that concept a little more, if there is only ever one source of a particular kind event in some containment hierarchy (up to the point of the object the handler is bound to) then again, the ID of that source doesn't matter, at least for the purpose of binding and finding event handlers for that event type. And it definitely doesn't matter if the same ID is used in another containment hierarchy because that other one will never be seen here. Again, the specific ID of the widget is not needed.

    obj = SomeWidget(self, wx.ID_ANY, ...)
    self.Bind(wx.EVT_SOMETHING, self.myHandler)
    
  3. When there can be multiple sources of the same event type within a containment hierarchy which need to be routed to different handlers then the third parameter of Bind() (named 'source') can be used to accomplish that, and still there is no need to use and know specific ID values.

    objA = SomeWidget(self, wx.ID_ANY, ...)
    objB = SomeWidget(self, wx.ID_ANY, ...)
    self.Bind(wx.EVT_SOMETHING, self.myAHandler, objA)
    self.Bind(wx.EVT_SOMETHING, self.myBHandler, objB)
    
  4. Thanks to the magic of Python the source parameter of the Bind() method can take any kind of object which has a GetId() method. That includes all windows/widgets, menu and toolbar items (which are returned by the methods which add the items to the menu or toolbar), timers, and so forth. If there is anything that can be the source of an event that does not have a GetId() method then I would consider that to be a bug and it should be reported. Since it's Python then it can also be non-UI objects that have a GetId() method, if that makes sense for the design of your application.

    item = menu.Append(wx.ID_ANY, "&Foo", "Do some foo stuff")
    self.Bind(wx.EVT_MENU, self.onDoFoo, item)
    
  5. If you ever do need to know the ID of an item then you can just call it's GetId() instead of creating a preset constant.

    item = menu.Append(wx.ID_ANY, "&Foo", "Do some foo stuff")
    toolbar.AddTool(item.GetId(), "Foo", fooBmp, "Do Some Foo stuff")
    self.Bind(wx.EVT_MENU, self.onDoFoo, item) # works for both items
    
  6. One other common place where I've seen people wanting to use specific IDs is in event handlers to differentiate behavior based on the source of the event. For example:

    def OnHandleButtons(self, evt):
        if evt.GetId() == ID_A:
            self.doSomething()
        elif evt.GetId() == ID_B:
            self.doSomethingElse()
        ...
    

    However it's just as easy to compare the event's source object itself, and is also a stronger way to dispatch based on source in the rare case where there might be a duplicate ID conflict.

    def OnHandleButtons(self, evt):
        if evt.GetEventObject() is self.objA:
            self.doSomething()
        elif evt.GetEventObject() is self.objB:
            self.doSomethingElse()
        ...
    

    On the other hand, it is also simple to bind a separate handler for each of the cases above and that would also be a better OOP design.

This obviously doesn't cover all use cases now and forever, but it should show that the need to use and reuse preset ID values is lower than some people may think, and that the desire is that they should not be needed at all.

wxPython 4.0.1 Released

"Lemonade"

wxPython 4.0.1 is now available at PyPI, with some additional files at the Extras archive.

This release is a quick hot-fix of some issues discovered in 4.0.0 just after the release, plus a bit of low-hanging fruit that was easy to squeeze in too. Changes in this release include the following:

Read more…

Building wxPython for Linux via Pip

[ Post updated 2018-02-03, see new Build Steps section below. ]

wxPython Wheels for Linux?

Before reading further, you may want to check and see if there are already some wxPython wheels available for your flavor of Linux. A few are built as part of the release process and are available from one of wxPython's servers. More details and some links are on the download page.

If there are no existing wheels there for your distro, (or perhaps a close relative,) then read on to find out why we can't just provide wheels for all Linuxes, and what you need to build one for yourself.

The Problem

There have been some issues flowing into Phoenix's issue tracker since the release of wxPython 4.0.0b1 related to installation issues on Linux using pip, which have caused some overhead and soaked up unnecessary amounts of time. So lets start with getting some of the basics out of the way. There are a lot of flavors of linux. To name a few there's the Debian family, Debian, Ubuntu, Kubuntu, Elementary, Mint, etc., Arch, Gentoo, RHEL and CentOS, and so on. Each flavor has differences which can make binary distributions incompatible across flavors.

Why does this affect wxPython you may ask? It's just a Python package, and Python source is independent across operating systems after all, right?. Well, not all Python packages are just Python. wxPython as an example contains binary extension modules (compiled C or C++ code that is platform and architecture dependent.) wxPython by default also contains a copy of the compiled version of the wxWidgets library written in C++, which also depends on other 3rd party libraries which need to not only be present at runtime, but also have their development-related files present at wxWidgets' and wxPython's compile time.

Pip in its infinite wisdom can detect this, and knows how to select the appropriate binary wheel for the following criteria:

  • OS (Windows, macOS, Linux)
  • Architecture (i386, x86_64, etc)
  • Python Version (2.7, 3.5, 3.6, etc)

See how pip doesn't care about the specific linux distribution? That's the issue. The binary content and dependencies of wxPython can't be delivered consistently via pip. There are some efforts to get around this (eg. PEP 513 a.k.a. manylinux1) but they don't quite work for wxPython yet. Packages that are able to fit into the very narrow manylinux1 requirements can be hosted on PyPI and will install with pip just as smoothly as pure-python packages do. Unfortunately the manylinux1 spec does not include a version of GTK+ and its dependencies that are new enough to be able to provide all the features that wxWidgets requires.

The Fix

In order to deploy to linux systems wxPython4 (Phoenix) simply builds itself from a source tarball as part of the pip setup process. All of the code generated by wxPython's build system is already present in the tarball, it merely needs to be compiled. This causes a very lengthy installation times, but is a necessary evil. Because the build is just that, a build, you will need all of wxWidgets and wxPython's binary dependencies present at build time. wxWidgets' configure will be run, and if it detects missing libraries the whole build, and therefore the pip installation, will fail.

What You Need

You will need the following packages (please consult your distribution's package list for the appropriate package names) and their dependencies:

  • python-dev (for your version of python)
  • gtk (preferably version 3, but depends on your needs)
  • gstreamer
  • gstreamer-plugins-base
  • glut
  • libwebkitgtk (matching your gtk version)
  • libjpeg
  • libpng
  • libtiff
  • libsdl
  • libnotify
  • libsm

on Debian based systems, or other systems that separate development packages from standard packages, you will need the corresponding -dev or -devel package in addition to the standard package.

Once the appropriate packages are present on your system then wxPython should build with no problems, either with pip or from a source tree extracted from the source tarball. If it still doesn't work for you then be sure to look closely at the build log as there will likely be some clues there that may point you in the right direction. For example, this:

checking for OpenGL headers... not found
checking for GL/gl.h... no
configure: error: OpenGL libraries not available

will tell you that the OpenGL libraries are missing. They are usually a dependency of the glut or freeglut packages and should have been installed along with that library, but perhaps your system's dependencies are different and you'll need to do a little investigation to determine the proper system packages that need to be installed.

Build Steps

Once you have installed the required depenency libraries, it should take just a few steps to build a wxPython that will work on your system with your Python. The steps shown here are just one option, but seems to be one of the simpler approaches to take, and will require nothing extra to be installed in your system Python. These instructions assume that you will be using a 3.4+ version of Python and that the executable is called "python3". If you are using 2.7 or the binary is called something else then adapt accordingly.

Step 1: The first thing we'll do is create and activate a new virtual environment for the build and the initial testing. This is optional, but highly recommended as it will ensure that there is nothing left over from a previous build that could trip things up. The last two commands shown here are just so you can verify that the python and pip commands are now being found in the new virtual environment instead of from the system or other Python environment.

cd [some tmp folder]

python3 -m venv builder_py
source builder_py/bin/activate

which python
which pip

Step 2: Next, you'll want to update pip and add a few more packages.

pip install -U pip
pip install -U six wheel setuptools

Step 3: Use pip to download the latest source archive from PyPI.

pip download wxPython

Step 4: Use pip to build a wxPython wheel file. We'll also redirect the build output to a file so you can review it later if needed. This step will take a while to complete, as it will be compiling all the wxWidgets and wxPython source code, but you'll be able to watch the build output to monitor the progress. Be sure to use the actual name of the downloaded source archive file, which may be different than the one shown here.

pip wheel -v wxPython-4.0.1.tar.gz  2>&1 | tee build.log

Step 5: If the build was successful then you should now have a wxPython wheel file in the current working directory. If there was a problem then review the build.log file and see if you can spot any clues as to what dependencies may be missing or out of date. (Build problems from wxPython release sources are almost always due to missing dependencies.) Once you think you have solved the problem go back to step 4 and try the build again.

Step 6: The next step is to install the wheel file in the virtual environment and give it a quick test run. (Use the actual name of the wheel file you built, which may be different than the one shown here.)

pip install wxPython-4.0.1-cp35-cp35m-linux_x86_64.whl

python -c "import wx; a=wx.App(); wx.Frame(None,title='hello world').Show(); a.MainLoop();"

You should see a new window open with a "hello world" title bar, which will indicate that this build was successful and this wxPython wheel can be used on your system. You can now use pip to install the wheel file in other Python environments or virtual environments that use the same base Python executable that you used for this build.

FAQ

Q1: "Why can't you just install the necessary packages as part of wxPython's installation"

A1: Lots of good reasons, among them are: Pip is NOT your linux package manager, Phoenix is not responsible for maintaining your system.

Q2: "I can install PyQt(4/5) just fine via pip! Why can't wxPython do the same?"

A2: Qt does not depend on system provided libraries other than the low- level basic libs. wxWidgets does, it's one of the defining differences of the two toolkits. As such PyQt can deliver to all linuxes in the same manner.