
How I set up a calibre plugin development environment in PyCharm
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
debugpy
server (docs)
*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
.py
in your plugin like so:The “
the_eye
” in the remote path is based on theplugin-import-name-the_eye.txt
in 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-pycharm
into your plugin’s__init__.py
from there: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
cd
into your plugin’s directory calibre-customize -b .
calibre-debug -g
- 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
src
directory within the cloned repository as content root, like so: - Add a path mapping from the absolute path to the
src/calibre
directory to “calibre
” in the remote debugging configuration - Start calibre with
export CALIBRE_DEVELOP_FROM="..."; calibre-debug -g
where...
is the absolute path to thatsrc
directory
(Based on the official documentation)