webdebug

Webdebug


License
MIT
Install
pip install webdebug==1.1.0

Documentation

webdebug

Build Status MIT License PyPi Version Supports Python 3.4+, including PyPy

Make werkzeug's interactive debugger available in two lines of code.

Have you always wished to have better debugging experience with python? We all know how frustrating it is to have your long running tasks throwing error, unhandled, leaving you clueless with a bunch of meaningless trace stack.

You then want to setup a debugger, but again, nothing works out-of-the-box! Now you are frustrated.

webdebug is to solver the problem by the following work flow:

  • Run your python code > unhandled exception > set-up werkzeug debug wep app > trigger notification (optional) > you debug interactively

screen screen2

Installation

pip install webdebug

Requirement

  • Python 3.4 +
  • werkzeug 0.14 +

The werkzeug debugger

webdebug simply makes werkzeug debugger available to your python scripts. For more information, please visit werkzeug's documentation

Use

WARNING: Do not, do not, and do not X 1,000 times, use this in production environments which is connect to the external, because the debugger allow arbitrary code execution.

1. Run as module

Usage: python -m webdebug [--host] address [--port] port [--pin] pin your_python_file.py

$ python -m webdebug your_python_script.py

or

$ python -m webdebug --host localhost --port 54321 --pin 12345 your_python_script.py

It's that easy! Now that your script will stop and host a werkzeug debugger in case of unhandled exception.

2. Enable web debug in you script

from webdebug import set_web_debug,unset_web_debug

set_web_debug()
0 / 0

#or

set_web_debug(host='localhost' ,pin='12345',port='54321',callbacks=[])
0 / 0

# to un-set web debug use:

unset_web_debug()

caveat

set_web_debug catch exception via sys.excepthook which is only trigger if exception is unhandled. If you use pipeline framework like luigi which handles every exception, set_web_debug will not work as expected. You are encouraged to use With Block instead.

3. With Block

from webdebug import web_debug

with web_debug:
    0/0

# or


with web_debug(host='localhost',pin='12345',port='54321',callbacks=[]):
    0/0
    
* Debugger is active!

4. Function decorator

from webdebug import web_debug

@web_debug
def err():
    0 / 0

# or

@web_debug()
def err():
    0 / 0

# or

@web_debug(catch=True,host='localhost',pin='12345',port='54321',callbacks=[])
def err():
    0 / 0
 
err()

* Debugger is active!

Behavior of argument catch:

The following will trigger webdebug:

@web_debug(catch=True)
def err():
    0 / 0

try:
    err()
except:
    ...

* Debugger is active!

and the following will not

@web_debug(catch=False)
def err():
    0 / 0

try:
    err()
except:
    ...

# nothing happens

5. Start server from exception

from webdebug import start_server

try:
    99/0
except Exception as ex:
    start_server(ex)

# or

try:
    99/0
except Exception as ex:
    start_server(ex,host='localhost',pin='12345',port='54321')

* Debugger is active!

Callback/Notification

You can extend webdebug.callback.BaseCallBack and webdebug.callback.Notifier classes.

This package provides an out-of-the-box Gmail notifier.

To use the notifier, you need a Gmail account and an app password:

from webdebug import set_web_debug,GmailNotifier


set_web_debug(callbacks=[GmailNotifier(gmail_user='frompythonimportme@gmail.com'
                                       ,gmail_password='xxxxxxxx'
                                       ,to='frompythonimportme@gmail.com')])


99/0

screen3

Exceptions exclusion

web_debug,set_web_debug can be passed with exclude (tuple of exception)argument, so the webdebug will ignore the exception type.

from webdebug import set_web_debug

set_web_debug(exclude=(ZeroDivisionError,))
0/0

#raise ZeroDivisionError as python normally world.

Shutting down webdebug server

Fire a get request to / from you browser visit:

http://[host]:[port]?shutdown=Y

Exception handling after shutting down webdebug

webdebug aims to be a plug-and-play package which introduce the least behavior changes to your python code. Exceptions are raised again after webdebug is shut down. If you find any strange behaviors, please report an issue.

Disabling webdebug on environment level

set environment variable 'webdebug' = 'false'.

Other options

  1. Bind host = '0.0.0.0' if you want to connect webdebug from external.

    WARNING: The debugger allow arbitrary code execution from external. Only do it if you know what you are doing!

  2. Bind port = 0 for a random available port.