t %}
How I set up a calibre plugin development environment in PyCharm
The PyCharm debugger paused on a breakpoint within my calibre plugin’s code

How I set up a calibre plugin development environment in PyCharm

2020-11-07

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:

    Edit configuration for remote debugging in PyCharm

  • Add path mappings for every single .py in your plugin like so:

    Path mappings for remote debugging in PyCharm

    The “the_eye” in the remote path is based on the plugin-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:

    A line breakpoint in PyCharm

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:

Remote debugging of a calibre plugin in PyCharm

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 content root to project structure in PyCharm

  • 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 that src directory

(Based on the official documentation)

#mac #pycharm #calibre #development