Porting Anki 2.0 add-ons
- Python 3
- Qt5 / PyQt5
- Single .py add-ons need their own folder
- Folders are deleted when upgrading
- Supporting both 2.0 and 2.1 in one codebase
- Webview Changes
- Reviewer Changes
- Add-on Configuration
Anki 2.1 requires Python 3 or later. After installing Python 3 on your machine, you can use the 2to3 tool to automatically convert your existing scripts to Python 3 code on a folder by folder basis, like:
2to3-3.8 --output-dir=aqt3 -W -n aqt mv aqt aqt-old mv aqt3 aqt
Most simple code can be converted automatically, but there may be parts of the code that you need to manually modify.
Qt5 / PyQt5
The syntax for connecting signals and slots has changed in PyQt5. Recent PyQt4 versions support the new syntax as well, so the same syntax can be used for both Anki 2.0 and 2.1 add-ons.
More info is available at http://pyqt.sourceforge.net/Docs/PyQt4/new_style_signals_slots.html
One add-on author reported that the following tool was useful to automatically convert the code: https://github.com/rferrazz/pyqt4topyqt5
The Qt modules are in 'PyQt5' instead of 'PyQt4'. You can do a conditional import, but an easier way is to import from aqt.qt - eg
from aqt.qt import *
That will import all the Qt objects like QDialog without having to specify the Qt version.
Single .py add-ons need their own folder
Each add-on is now stored in its own folder. If your add-on was
demo.py, you’ll need to create a
demo folder with
If you don’t care about 2.0 compatibility, you can just rename
If you plan to support 2.0 with the same file, you can copy your
original file into the folder (
demo/demo.py), and then
import it relatively by adding the following to
from . import demo
The folder needs to be zipped up when uploading to AnkiWeb. For more info, please see sharing add-ons.
Folders are deleted when upgrading
When an add-on is upgraded, all files in the add-on folder are deleted. The only exception is the special user_files folder. If your add-on requires more than simple key/value configuration, make sure you store the associated files in the user_files folder, or they will be lost on upgrade.
Supporting both 2.0 and 2.1 in one codebase
Most Python 3 code will run on Python 2 as well, so it is possible to update your add-ons in such a way that they run on both Anki 2.0 and 2.1. Whether this is worth it depends on the changes you need to make.
Most add-ons that affect the scheduler should require only minor changes to work on 2.1. Add-ons that alter the behaviour of the reviewer, browser or editor may require more work.
The most difficult part is the change from the unsupported QtWebKit to QtWebEngine. If you do any non-trivial work with webviews, some work will be required to port your code to Anki 2.1, and you may find it difficult to support both Anki versions in the one codebase.
If you find your add-on runs without modification, or requires only minor changes, you may find it easiest to add some if statements to your code and upload the same file for both 2.0.x and 2.1.x.
If your add-on requires more significant changes, you may find it easier to stop providing updates for 2.0.x, or to maintain separate files for the two Anki versions.
Qt 5 has dropped WebKit in favour of the Chromium-based WebEngine, so Anki’s webviews are now using WebEngine. Of note:
You can now debug the webviews using an external Chrome instance, by setting the env var QTWEBENGINE_REMOTE_DEBUGGING to 8080 prior to starting Anki, then surfing to localhost:8080 in Chrome.
As a result of this asynchronous behaviour, editor.saveNow() now requires a callback. If your add-on performs actions in the browser, you likely need to call editor.saveNow() first and then run the rest of your code in the callback. Calls to .onSearch() will need to be changed to .search()/.onSearchActivated() as well. See the browser’s .deleteNotes() for an example.
WebEngine doesn’t provide a keyPressEvent() like WebKit did, so the code that catches shortcuts not attached to a menu or button has had to be changed. setStateShortcuts() fires a hook that can be used to adjust the shortcuts for a given state.
Many small 2.0 add-ons relied on users editing the sourcecode to customize them. This is no longer a good idea in 2.1, because changes made by the user will be overwritten when they check for and download updates. 2.1 provides a Configuration system to work around this. If you need to continue supporting 2.0 as well, you could use code like the following:
if getattr(getattr(mw, "addonManager", None), "getConfig", None): config = mw.addonManager.getConfig(__name__) else: config = dict(optionA=123, optionB=456)