In case something does not work the way you want there are several ways to debug things.

Viewing module contents

We recommend to create a simple file with just the part that does not work. We usually call this file and remove it before the actual commit.

To reveal internals of this Python source code, you can use following options:

  • astboom < will show you pretty-printed ast contents

  • tokelor will show you pretty-printed token stream

It might not be enough to find some complex cases, but it helps.

Test-driven development

A lot of people (including @sobolevn) finds test-driven development really useful to design and debug your code.


  1. Write a single test that fails for your new feature or exposes a bug

  2. Run it with pytest tests/full/path/to/your/

  3. Use the magic of print and ast.dump to view the contents of nodes

  4. Fix the bug or implement a new feature

  5. Make sure that everything works now: tests must pass

  6. Done!

Interactive debugging

We recommend to use ipdb for interactive debugging (it is already included as a development package to this project).

To start interactive debugging session you will need to:

  1. Set export PYTHONBREAKPOINT=ipdb.set_trace environment variable

  2. Put breakpoint() call in places where you need your debugger to stop

  3. Run your program as usual, debugger will stop on places you marked

This way allows to view local variables, execute operations step by step, debug complex algorithms.

Visual debugging

One can use vscode or pycharm to visually debug your app. In this case you need to setup appropriate entrypoints and run your app in debug mode.