Qt 5 to Qt 6 Migration Guide
============================
Some notes and recommendations regarding the migration of Qt 5 to Qt 6, and PyQt 5 to PySide 6.
Included in these notes are some external links to both official and unofficial sites.

Importing Qt modules
--------------------

Until Katana 7.5 (last with Qt 5), Qt modules are imported with the following Python code:

.. code-block:: python

  from PyQt5 import QtCore, QtGui, QtWidgets

Since Katana 8.0 (first with Qt 6), the equivalent Python code is:

.. code-block:: python

  from PySide6 import QtCore, QtGui, QtWidgets

In order to support conditionally importing the Qt modules based on which version of
Katana is being used, we recommend the following:

.. code-block:: python

  import KatanaInfo
  katanaVersion = int(KatanaInfo.version.split('.')[0])
  if katanaVersion >= 8:
    from PySide6 import QtCore, QtGui, QtWidgets
  else:
    from PyQt5 import QtCore, QtGui, QtWidgets

.. warning::
  It is discouraged to import the Qt modules using the widely known `try`/`except ImportError`
  pattern. If `PyQt5` or `PySide6` were available in the user's system, and an attempt to import
  one of them in a version of Katana which doesn't use it, Katana could wrongly succeed at
  importing them, leading to obscure fatal errors.


Qt 5 to Qt 6 Migration Notes
----------------------------

Qt have an extensive guide for migrating from Qt 5 to Qt 6, which can be found here:

- https://doc.qt.io/qt-6/portingguide.html

The Python bindings for Qt largely follow the C++ Qt naming and structure. So changes listed above
should, in most cases, apply equally to Python code. A good default strategy when coming up to
issues in your Qt code, is to check the above guide for any mentions of the problematic Qt code.
Another strategy worth mentioning is that Qt maintain API reference documentation for both their
5.x and 6.x lines. You can compare the API for a class in 5.x against 6.x. For example, the
documentation for the `QComboBox`` class in Qt 5 can be found at

- https://doc.qt.io/qt-5/qcombobox.html

Whereas the documentation for Qt 6 can be found at

- https://doc.qt.io/qt-6/qcombobox.html



PyQt 5 to PySide 6 Migration Notes
----------------------------------

At the time of writing this, no official and up-to-date migration documentation exists for porting
PyQt 5 to PySide 6. The following may prove useful:

- `Differences between PyQt and PySide, but with a focus on Qt 4 <https://wiki.qt.io/Differences_Between_PySide_and_PyQt>`_.
- `PySide6 documentation homepage <https://wiki.qt.io/Qt_for_Python>`_.
- `A third-party guide on the differences between PyQt 6 and PySide 6 <https://www.pythonguis.com/faq/pyQt6-vs-pyside6/>`_.