PyCharm setup for add-on debugging

Development
1

I thought I would share my current workflow for add-on development in PyCharm. It admittedly feels like a bit of a ‘hack’, so I would warmly welcome any comments/criticisms from more experienced developers. But hopefully it will help a few people out.

My main goals were as follows:

  • Be able to launch Anki from within PyCharm
  • Run in debug mode so I could see print statement outputs and place breakpoints in both my own add-on code and the Anki source code (eg. to see within Anki how variables are set, the flow between functions, etc.)

I had a lot of head-scratching to get a process working since the switch to the Bazel build system. I still have not been able to actually launch Anki within PyCharm from the downloaded source code, only from pre-built wheels as shown below.

Project structure

This isn’t strictly necessary, but I use the following project structure prescribed by anki-addon-builder:anki-addon-builder

{my_addon_name}
└── runanki.py (copied from anki source; used to run in Pycharm)
└── addon.json [required only for aab]
└── src
    └── {my_addon_name}
 			   ├── project files (__init__.py, etc.)

runanki.py

A key here is the runanki.py file. This is what allows Anki to be launched from within the PyCharm project. I copied the file directly from the Anki source code, but its contents are as follows:

#!/usr/bin/env python3
# Copyright: Ankitects Pty Ltd and contributors
# License: GNU AGPL, version 3 or later; http://www.gnu.org/licenses/agpl.html

import os
import sys

try:
    import bazelfixes

    bazelfixes.fix_pywin32_in_bazel()
    bazelfixes.fix_extraneous_path_in_bazel()
except ImportError:
    pass

import aqt

if not os.environ.get("ANKI_IMPORT_ONLY"):
    aqt.run()

Virtual environment setup

Create a virtual environment and install anki and aqt. You can either build wheels from the source code (as detailed in the documentation) or download the current versions from PyPI. This can be done on the command line, but a simpler method within PyCharm is detailed below.

Open up the root folder of the project in PyCharm. Open the PyCharm Preferences dialog and select Project > Python Interpreter on the sidebar. In the ‘Python Interpreter’ dropdown, select ‘Show All…’, then click the ‘Add’ button to create a new virtual environment.

image-20220220124215956
image-202202201242159561804×811 153 KB

image-20220220124346728
image-202202201243467281132×532 181 KB

Insert any desired location for the virtual environment and select the Python interpreter (ideally, it should match the Python version used in the latest Anki build).

image-20220220124527491
image-202202201245274911750×950 146 KB

Now, click the ‘+’ button to install the aqt and anki packages.

image-20220220124735625
image-202202201247356251564×860 110 KB

image-20220220124850125
image-202202201248501251396×666 48.1 KB

Run configuration

Add a new run/debug configuration. For the Script Path, select the runanki.py file in the project directory. Python Interpreter should be Python in the project’s virtual environment.

If you want to automatically load a certain Anki profile (eg. a separate one for development), you can add -p Development_profile_name to the Parameters field.

image-20220220224400947
image-20220220224400947770×292 24.9 KB

image-20220220224738629
image-202202202247386291067×616 80.1 KB

image-20220220225222020
image-202202202252220201692×1168 172 KB

Running Anki in debug mode

If you click the debug (or run) button in the upper right of the window, it should now launch Anki. The add-on itself won’t be available to Anki yet, but we’ll fix that shortly (see below).

You can find the anki source files in the packages under External Libraries in the sidebar. You can place breakpoints in any file to pause execution (eg. to examine the values of variables or to step through the code execution).

image-20220220231627255
image-202202202316272551612×1172 192 KB

image-20220220234017571
image-202202202340175712486×1064 378 KB

Activating the add-on

The add-on directory needs to be within the Anki add-ons directory in order for it to be loaded. This can be done by creating an alias. On the Mac, a regular alias won’t work and you have to create a symlink using the Terminal as follows:

ln -s "/{PATH TO PROJECT DIR}/my_addon/src/my_addon" \
"/{PATH TO ANKI ADDONS}/addons21/{MY ADDON NAME}"

Note that only the my_addon directory within the src directory is symlinked, not the root project directory. Replace the curly bracket components, and whatever the symlink folder is named will be displayed as the add-on name in Anki.

After launching Anki, check to make sure that the add-on is active using the usual Add-ons menu item.

Now, you can add breakpoints to your add-on code and see print statements in the console.

image-20220221000916995
image-202202210009169951202×566 70.5 KB

Suppressing the Import window

For some reason, when you launch Anki in debug mode (not run mode), it will always show the Import window on startup.

image-20220220231457028
image-202202202314570281134×508 61.9 KB

You can suppress this by making a change to the aqt/main.py file. Of course, you shouldn’t really edit files in the libraries in this way (and PyCharm will show a warning), so look at this as a bit of a hack.

In the file aqt/main.py, find the function def onAppMsg(self, buf: str). Near the end of the function, you will see the following:

# import / add-on installation
if is_addon:
    self.installAddon(buf)
else:
    self.handleImport(buf)

Comment out the line self.handleImport(buf) and replace it with pass:

# import / add-on installation
if is_addon:
    self.installAddon(buf)
else:
    # self.handleImport(buf)
    pass

This should stop the Import window from displaying on startup.

9 Likes
2

Thank you for this contribution.

I have used this gracious resource to help create a tutorial on YouTube explaining this process.

1 Like