Metadata-Version: 2.1
Name: web-pdb
Version: 1.5.3
Summary: Web interface for Python's built-in PDB debugger
Home-page: https://github.com/romanvm/python-web-pdb
Author: Roman Miroshnychenko
Author-email: roman1972@gmail.com
License: MIT License
Keywords: pdb remote web debugger
Platform: any
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: Framework :: Bottle
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Debuggers
Requires-Dist: bottle
Requires-Dist: asyncore-wsgi (>=0.0.4)

Web-PDB
#######

.. image:: https://travis-ci.org/romanvm/python-web-pdb.svg?branch=master
  :target: https://travis-ci.org/romanvm/python-web-pdb
  :alt: Travis-CI tests
.. image:: https://badge.fury.io/py/web-pdb.svg
  :target: https://badge.fury.io/py/web-pdb
  :alt: PyPI version

Web-PDB is a web-interface for Python's built-in `PDB`_ debugger.
It allows to debug Python scripts remotely in a web-browser.

Features
========

- Responsive design based on `Bootstrap`_.
- Python syntax highlighting with `Prism`_ ("Okaida" theme).
- Supports all PDB features.
- Standard input and output can be redirected to the web-console
  to interact with Python scripts remotely.
- **Current file** box tracks current position in a file being executed.
  Red line numbers indicate breakpoints, if any.
- **Globals** and **Locals** boxes show local and global variables in the current scope.
  Special variables that start and end with double underscores ``__`` are excluded
  (you can always view them using PDB commands).
- Human-readable Unicode literals for Python 2.
- Command history that stores up to 10 last unique PDB commands (accessed by arrow UP/DOWN keys).

.. figure:: https://raw.githubusercontent.com/romanvm/python-web-pdb/master/screenshot.png
  :alt: Web-PDB screenshot
  :width: 640px
  :height: 490px

  *Web-PDB console in Chrome browser*

Usage
=====

Install Web-PDB into your working Python environment::

  pip install web-pdb

Insert the following line into your Python program at the point where you want
to start debugging:

.. code-block:: python

  import web_pdb; web_pdb.set_trace()

The ``set_trace()`` call will suspend your program and open a web-UI at the default port ``5555``
(port value can be changed). Enter in your browser's address bar:
``http://<your Python machine hostname or IP>:5555``,
for example ``http://monty-python:5555``,
and you should see the web-UI like the one on the preceding screenshot.
Now you can use all PDB commands and features. Additional **Current file**, **Globals**
and **Locals** information boxes help you better track your program runtime state.

**Note**: it is strongly recommended to work with the Web-PDB web-UI only in one browser session.
With more than one browser window accessing the web-UI it may display incorrect data in one or more
browser sessions.

Subsequent ``set_trace()`` calls can be used as hardcoded breakpoints.

Web-PDB is compatible with the new `breakpoint()`_ function added in Python 3.7.
Set environment variable ``PYTHONBREAKPOINT="web_pdb.set_trace"`` to launch Web-PDB
with ``breakpoint()``.

Additionally, Web-PDB provides ``catch_post_mortem`` context manager that can catch
unhandled exceptions raised within its scope and automatically start PDB post-mortem debugging session.
For example:

.. code-block:: python

  import web_pdb

  with web_pdb.catch_post_mortem():
      # Some error-prone code
      assert foo == bar, 'Oops!'

For more detailed info about the Web-PDB API read docstrings in the ``./web_pdb/__init__.py`` file.

The ``inspect`` Command
-----------------------

Web-PDB provides ``inspect`` or ``i`` command that is not present in the original PDB.
This command outputs the list of object's members along with their values.
Syntax: ``inspect <object_name>`` or ``i <object_name>``.

Special members with names enclosed in double underscores (``__``) are ignored.

Considerations for Multithreading and Multiprocessing Programs
==============================================================
Multithreading
--------------

Web-PDB maintains one debugger instance that traces only one thread. You should not call ``set_trace()``
from different threads to avoid race conditions. Each thread needs to be debugged separately one at a time.

Multiprocessing
---------------

Each process can have its own debugger instance provided you call ``set_trace`` with a different port value
for each process. This way you can debug each process in a separate browser tab/window.
To simplify this you can use ``set_trace(port=-1)`` to select a random port between 32768 and 65536.

Compatibility
=============

- **Python**: 2.7, 3+
- **Browsers**: Firefox, Chrome (all modern browsers should work)

License
=======

MIT, see ``LICENSE.txt``.

The debugger icon made by `Freepik`_ from `www.flaticon.com`_ is licensed by `CC 3.0 BY`_.

.. _PDB: https://docs.python.org/3.6/library/pdb.html
.. _Bootstrap: http://getbootstrap.com
.. _Prism: http://prismjs.com/
.. _Freepik: http://www.freepik.com
.. _www.flaticon.com: http://www.flaticon.com
.. _CC 3.0 BY: http://creativecommons.org/licenses/by/3.0/
.. _breakpoint(): https://docs.python.org/3/library/functions.html#breakpoint


Changelog
#########

v.1.5.3

* Fixed the issue with closed debugger still being stored in ``active_instance``
  class property that prevented starting a new debugger session (thanks to **maiamcc**).

v.1.5.2
=======

* Updated frontend dependencies.

v.1.5.1
=======

* Fixed using ``inspect`` command for variables with ``None`` values.

v.1.5.0
=======

* Added ``inspect`` command.

v.1.4.4
=======

* Upgrade Prism.js to v.1.15.0

v.1.4.3
=======

* Use gzip compression instead of deflate for web-console endpoints
  (`more info <https://stackoverflow.com/a/9856879/4819775>`_).

v.1.4.2
=======

* Bump ``asyncore-wsgi`` dependency version. This fixes issues with the web-UI
  on some platforms.
* Code cleanup.

v.1.4.1
=======

* Use full path for setting and removing breakpoints.

v.1.4.0
=======

* Replaced a wsgiref-based multi-threaded WSGI server with a single-threaded
  asynchronous WSGI/WebSocket server.
* Implemented WebSockets instead of periodic back-end polling for retrieving
  updated debugger data.

v.1.3.5
=======

* Fix crash when clearing a breakpoint on Linux.
* Fix autoscrolling on large files.
* Move frontend to modern JavaScript syntax and tooling.
* Optimize Python syntax highlighting performance.

v.1.3.4
=======

* Fix a bug with patched ``cl`` command not working.

v.1.3.3
=======

* Fixed setting ``set_trace()`` at the last line of a Python script.
* Fixed clearing a breakpoint at setups with the current workdir different
  from the current module directory.

v.1.3.2
=======

* Internal changes.

v.1.3.1
=======

* Now if web-console data haven't changed
  the back-end sends "null" response body instead of a 403 error.

v.1.3.0
=======

* Implemented a multi-threaded WSGI server to increase responsiveness of the web-UI.

v.1.2.2
=======

* Added deflate compression for data sent to a browser.
* Attempt to fix **Current file** box auto-scrolling.

v.1.2.1
=======

* Logger fix.

v.1.2.0
=======

* Minor UI redesign.
* Added a quick action toolbar and hotkeys for common commands.
* Added a quick help dialog.
* Breakpoints can be added/deleted with a click on a line number.
* The **Currrent file** box is not auto-scrolled if the current line hasn't changed.
* Multiple ``set_trace()`` and ``post_mortem()`` calls are processed correctly.
* Added random web-UI port selection with ``port=-1``.

v.1.1.0
=======

* Initial PyPI release


