pdbe — a feature for internal Python debugger. Work with debugging in the Git style

The following article will describe debug tool called pdbe. It is a tool, that allows you to debug the whole project at once, particular application or separate files when it is needed. For example, in cases of learning how frameworks that you usually use work from the inside, or any individual abstracts like response-request life-cycle of view.

Motivation

There are many situations, when you need to debug an unfamiliar project with tens of thousands of code lines, or check functions traceback as a response to the request. Imagine, if you could refresh a page and easy know what exactly handle your request.

What does pdbe exactly do

The pretty simple idea of pdbe is to insert import pdb; pdb.set_trace() statement under each function declaration in specified file or bunch of files, then trigger something anywhere and debug code, that process request.

You don’t need to investigate, what you need to debug. You don’t need to pay attention to excess code lines — just go ahead and debug your stuff.

How to install

This tool is a simple Python package implemented command line interface, so install it via pip.

$ pip3 install pdbe

Usage

There are two points of using: common usage — inserting and clearing import pdb; pdb.set_trace() statements directly, advanced usage — commit, log and checkout your debug states (promised Git flow style).

Common usage

Let’s create one Python file, that will be used for providing examples of pdbe functionality result.

def first_function():     
    ...  
def second_function():     
    ...      
    def third_function():
        ...

To import import pdb; pdb.set_trace() statement under each function declaration in particular file, type the following command into a terminal.

$ pdbe --file project/file_flag.py

Also, imagine, that you work in your own project directory, so look at its structure example.

The emphasized files would be covered by the command.

As a result, we will get the following state.

def first_function():   
    import pdb; pdb.set_trace()  
    ...
def second_function():    
    import pdb; pdb.set_trace() 
    ...
    def third_function():
        import pdb; pdb.set_trace()
        ...

Obviously, you need a possibility to revert insertion, so that go ahead and easy use an additional --clear flag.

$ pdbe --file project/file_flag.py --clear

As a result, we will get the following state.

def first_function():     
    ...
def second_function():     
    ...
    def third_function():
        ...

As it is mentioned above, you are able to insert breakpoints (import pdb; pdb.set_trace() statements) into all existing Python files into a specified directory.

$ pdbe --dir project/dir_flag

The emphasized files would be covered by the command.

The same principle works for the Python files, located in nested directories (subdirectory within a directory). pdbe obediently checks all directories and finds needed files, and no matter how deep the specified directory is.

$ pdbe --ew project

If you are currently in the project directory and don’t want level up, just use a dot symbol.

$ pdbe --ew .

The emphasized files would be covered by the command.

Advanced usage

There are few features for working with debugging in the Git style: save state of import pdb; pdb.set_trace() statements, view logs of your state (message and datetime) and checkout to any committed state.

Here we go with committing the state of breakpoints. What does commit mean? It is when you ask pdbe to remember breakpoints position in your files. Let’s show it on the example.

def first_function():     
    ...
def second_function():     
    ...
    def third_function():
        ...

How you already know, insert import statements to the file with following command:

$ pdbe --file path/to/file.py

As a result.

def first_function():   
    import pdb; pdb.set_trace()  
    ...
def second_function():    
    import pdb; pdb.set_trace() 
    ...
def third_function():
        import pdb; pdb.set_trace()
        ...

Stop! There is could be a situation, when you change task or make pause in solving exactly this problem, or want to test your code as user (without debugging). Let’s keep in pdbe mind, that we have three import statements in the file above.

$ pdbe --commit 'Message handler debug'

And clear file.

$ pdbe --file path/to/file.py --clear

As a result.

def first_function():     
    ...
def second_function():     
    ...
    def third_function():
        ...

Imagine, that now you work on another ticket in your backlog, but extremely need to debug familiar logic in the file described above. There are two ways to do it: remember needed file or use pdbe logs.

$ pdbe --log
commit  | add336b6a204bb7b3abe76c296b67f92 
date    | 23:17:00 29-01-2018 
message | Message handler debug  
commit  | 4401cbeae73aece0216de9f4874451b6 
date    | 23:11:22 29-01-2018 
message | Users REST API get view

Great, now we have associations between the file we’ve been working on and message we’ve committed file’s state with. So checkout on this state.

$ pdbe --checkout add336b6a204bb7b3abe76c296b67f92

It works too dumb inside — pdbe creates hidden folder in the project directory and saves there all data, needed to handle features for the state. Don’t forget ignore these files in cases like .gitignore.

All changes (insertion of statements) were successfully reverted.

def first_function():   
    import pdb; pdb.set_trace()  
    ...
def second_function():    
    import pdb; pdb.set_trace() 
    ...
    def third_function():
        import pdb; pdb.set_trace()
        ...

What will be added in the next patches

1. There may be a situation, when you need to debug a project directly, but also want to hunt in which parts of the code your action is to handled. So it would be great to add a feature to insert logging as an import breakpoint.
2. Great, but hard — to have an opportunity to put a name of any object (variable, function or class) into pdbe tool and get the child-parent relationships into all project. It is useful to know how project’s abstracts talk to each other is cases.
3. Implement configuration file that for instance allows ignore some folders like migrations or use ipdb instead pdb.

I appreciate your attention

If you have an interest to pdbe, just visit Github-page of the project. Feel free to tell us about issues and please send us patches to make better.