# Migrating from version 2 to version 3

Version 3 is a new major version of the library which brings many new features, fixes bugs and improves the API. However, it is not fully backward compatible with the previous version.

The main changes are:

- New automated test suite

- New documentation

- guidata.guitest:

  - Added support for subpackages

  - New comment directive (`# guitest: show`) to add test module to test suite or to show test module in test launcher (this replaces the old `SHOW = True` line)

- guidata.dataset.datatypes.DataSet: new create class method for concise dataset creation

This section describes the steps to migrate your code from `guidata` version 2 to version 3.

The following table gives the equivalence between version 2 and version 3 imports.

For most of them, the change in the module path is the only difference (only the import statement have to be updated in your client code). For others, the third column of this table gives more details about the changes that may be required in your code.

Compatibility table
Version 2 | Version 3
`.userconfigio.BaseIOHandler` | `.io.BaseIOHandler`
`.userconfigio.WriterMixin` | `.io.WriterMixin`
`.userconfigio.UserConfigIOHandler` | `.io.INIHandler`
`.userconfigio.UserConfigWriter` | `.io.INIWriter`
`.userconfigio.UserConfigReader` | `.io.INIReader`
`.jsonio.JSONHandler` | `.io.JSONHandler`
`.jsonio.JSONReader` | `.io.JSONReader`
`.jsonio.JSONWriter` | `.io.JSONWriter`
`.hdf5io.HDF5Handler` | `.io.HDF5Handler`
`.hdf5io.HDF5Reader` | `.io.HDF5Reader`
`.hdf5io.HDF5Writer` | `.io.HDF5Writer`
`.gettext_helpers` | `.utils.gettext_helpers`
`.disthelpers` | removed
`.encoding` | `.utils.encoding`
`.encoding.transcode` | removed
`.encoding.getfilesystemencoding` | removed
`.qthelpers.text_to_qcolor` | removed
`.utils.update_dataset` | `.dataset.update_dataset`
`.utils.restore_dataset` | `.dataset.restore_dataset`
`.utils.to_string` | `.utils.misc.to_string.misc`
`.utils.decode_fs_string` | `.utils.misc.decode_fs_string.misc`
`.utils.assert_interfaces_valid` | `.utils.misc.assert_interfaces_valid.misc`
`.utils.get_module_path` | `.utils.misc.get_module_path.misc`
`.utils.is_program_installed` | `.utils.misc.is_program_installed.misc`
`.utils.run_program` | `.utils.misc.run_program.misc`
`.utils.run_shell_command` | `.utils.misc.run_shell_command.misc`
`.utils.getcwd_or_home` | `.utils.misc.getcwd_or_home.misc`
`.utils.remove_backslashes` | `.utils.misc.remove_backslashes.misc`
`.qtwidgets.RotatedLabel` | `.widgets.rotatedlabel.RotatedLabel`
`.qtwidgets.DockableWidgetMixin` | `.widgets.dockable.DockableWidgetMixin`
`.qtwidgets.DockableWidget` | `.widgets.dockable.DockableWidget`
`.utils.min_equals_max` | removed
`.utils.pairs` | removed
`.utils.add_extension` | removed
`.utils.bind` | removed
`.utils.trace` | removed
`.utils.utf8_to_unicode` | removed
`.utils.unicode_to_stdout` | removed
`.utils.localtime_to_isodate` | removed
`.utils.isodate_to_localtime` | removed
`.utils.FormatTime` | removed
`.utils.Timer` | removed
`.utils.tic` | removed
`.utils.toc` | removed
`.utils.is_module_available` | removed
`.utils.get_package_data` | removed
`.utils.get_subpackages` | removed
`.utils.cythonize_all` | removed