Wow, that was a pain. I’ve tried everything*:
- Using PyCharm’s “Attach to Process” (docs)
- Working with calibre’s built-in rpdb (docs)
- Attaching to a runnning process from VSCodium (docs)
- Setting up VSCodium’s
*OK, not everything. I could have tried debugging with Eclipse/PyDev.
Nothing worked on my MacBook (macOS Catalina 10.15.7). Until I installed a 30-day trial of PyCharm Professional (I usually use their free Community Edition), which supports remote debugging. This is what I did to make that work:
1. Set up a PyCharm project
- Create a new project in PyCharm and point it to the directory that holds the plugin you’re working on as content root
2. Add remote debugging with path mappings to the project
- In PyCharm, go to “Run” > “Edit Configurations…”
Click the “+” on the top left and choose “Python Debug Server”. This should give you something like this:
Add path mappings for every single
.pyin your plugin like so:
the_eye” in the remote path is based on the
plugin-import-name-the_eye.txtin my plugin directory, so change that accordingly. As well as the local paths, of course. Thanks T P who figured out that these mappings need to be 1-on-1 and posting that finding on the PyCharm forums ages ago.
- Start listening for a debug server with “Run” > “Debug…” and pick the new configuration you just created.
See the docs for more information on PyCharm’s remote debugging.
3. Add the debug server to your plugin
Figure out where your PyCharm is located and import
pydevd-pycharminto your plugin’s
sys.path.append('/Applications/PyCharm.app/Contents/debug-eggs/pydevd-pycharm.egg') import pydevd_pycharm pydevd_pycharm.settrace('localhost', stdoutToServer=True, stderrToServer=True, suspend=False)
Note that the default port is
5678, so no need to define it if you’re fine with that.
4. Add breakpoints
Click next to the line number in your plugin’s code to add a breakpoint where you want execution to pause, like so:
5. Build your plugin and start calibre
- Open up your terminal and
cdinto your plugin’s directory
calibre-customize -b .
- From within the interface do whatever action would trigger the function you added the breakpoint to.
6. Ignore the warnings and enjoy stepping through your code:
If you also want to step through calibre’s code, do this too:
git clone git://github.com/kovidgoyal/calibre.git
From PyCharm’s preferences go to “Project: …” > “Project Structure” and add the
srcdirectory within the cloned repository as content root, like so:
- Add a path mapping from the absolute path to the
src/calibredirectory to “
calibre” in the remote debugging configuration
- Start calibre with
export CALIBRE_DEVELOP_FROM="..."; calibre-debug -gwhere
...is the absolute path to that
(Based on the official documentation)