Changing the existing API

The simplest method of updating the API is just to change the existing API. This is obviously very simple for the developers, and there exists only one API at any given time. However, any existing applications depending on PySide would need to be constantly updated. Any amount of such changes would in practice discourage any developers from using PySide, and therefore, this approach would only be possible at the very early stages of any project when there are not yet any applications using the project.

Coinciding the API break with Python 3 transition

Python 3 is backwards incompatible with older Python versions both at the syntax and the standard library API levels. Since the users would need to adapt their code in any case, the thought of simultaneously updating the PySide API is an enticing one. The approach is tempting also from the API developers' perspective. Since Python 3 breaks the extension API compatibility in any case, this strategy cleanly splits the code to the old and the new APIs under the hood as well.

On the other hand, one might argue that the tandem update strategy will actually be more difficult to implement in practice. Not only will there be changes due to the Python 3 transition, but the visible API behaviour will be changed as well. In practice, the two changes would need to be performed sequentially to implement the features in a controlled manner.

The tandem update strategy would lead to a difficult upgrade path for existing applications. The recommended development model for upgrading from Python 2 to 3 is to utilize a specific 2to3 script to convert the script from Python 2.6 to the 3 syntax [2]. This will not work if the APIs are modified in an incompatible manner at the same time. With the library APIs breaking simultaneously, the developer would have no idea whether the problems in his application are due to the Python or the PySide changes.

When considering the alternatives, it is of importance that the tandem update strategy has been discouraged by Python core developers [1], to a great extent due to the reasons discussed above.

Separate imports for different API versions

The final API upgrade strategy is to disconnect the upgrade altogether from the Python version upgrade. In this case, the backwards-incompatible API would be placed in its own module. For example, the current QtCore library is imported using:

import PySide.QtCore

The new API would then utilize a different import:

import PySideFoo.QtCoreBar

This approach might arguably actually simplify implementing the new features as they would be only simple steps on top of the old API. Furthermore, Python 3 porting would only focus on the extension API differences instead of mixing the PySide API changes in the issue. For users, separate imports would provide for a standard upgrade path, removing any extra barriers for upgrading to Python 3.

The main drawback in this approach is the potentially increased maintenance effort. Two sets of APIs on two major Python versions need to be maintained. This may tie down the developers and decrease general project velocity.