Web-PDB
#######
.. image:: https://github.com/romanvm/python-web-pdb/actions/workflows/tests.yml/badge.svg
:target: https://github.com/romanvm/python-web-pdb/actions/workflows/tests.yml
:alt: GitHub Action 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).
- 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**: 3.6+
- **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
Raw data
{
"_id": null,
"home_page": "https://github.com/romanvm/python-web-pdb",
"name": "web-pdb",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": "",
"keywords": "pdb remote web debugger'",
"author": "Roman Miroshnychenko",
"author_email": "roman1972@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/16/8e/047b90ef574d76b550d3874d0888eadd6f7749114c49708e4eebd6a0d02d/web-pdb-1.6.2.tar.gz",
"platform": "any",
"description": "Web-PDB\n#######\n\n.. image:: https://github.com/romanvm/python-web-pdb/actions/workflows/tests.yml/badge.svg\n :target: https://github.com/romanvm/python-web-pdb/actions/workflows/tests.yml\n :alt: GitHub Action tests\n.. image:: https://badge.fury.io/py/web-pdb.svg\n :target: https://badge.fury.io/py/web-pdb\n :alt: PyPI version\n\nWeb-PDB is a web-interface for Python's built-in `PDB`_ debugger.\nIt allows to debug Python scripts remotely in a web-browser.\n\nFeatures\n========\n\n- Responsive design based on `Bootstrap`_.\n- Python syntax highlighting with `Prism`_ (\"Okaida\" theme).\n- Supports all PDB features.\n- Standard input and output can be redirected to the web-console\n to interact with Python scripts remotely.\n- **Current file** box tracks current position in a file being executed.\n Red line numbers indicate breakpoints, if any.\n- **Globals** and **Locals** boxes show local and global variables in the current scope.\n Special variables that start and end with double underscores ``__`` are excluded\n (you can always view them using PDB commands).\n- Command history that stores up to 10 last unique PDB commands (accessed by arrow UP/DOWN keys).\n\n.. figure:: https://raw.githubusercontent.com/romanvm/python-web-pdb/master/screenshot.png\n :alt: Web-PDB screenshot\n :width: 640px\n :height: 490px\n\n *Web-PDB console in Chrome browser*\n\nUsage\n=====\n\nInstall Web-PDB into your working Python environment::\n\n pip install web-pdb\n\nInsert the following line into your Python program at the point where you want\nto start debugging:\n\n.. code-block:: python\n\n import web_pdb; web_pdb.set_trace()\n\nThe ``set_trace()`` call will suspend your program and open a web-UI at the default port ``5555``\n(port value can be changed). Enter in your browser's address bar:\n``http://<your Python machine hostname or IP>:5555``,\nfor example ``http://monty-python:5555``,\nand you should see the web-UI like the one on the preceding screenshot.\nNow you can use all PDB commands and features. Additional **Current file**, **Globals**\nand **Locals** information boxes help you better track your program runtime state.\n\n**Note**: it is strongly recommended to work with the Web-PDB web-UI only in one browser session.\nWith more than one browser window accessing the web-UI it may display incorrect data in one or more\nbrowser sessions.\n\nSubsequent ``set_trace()`` calls can be used as hardcoded breakpoints.\n\nWeb-PDB is compatible with the new `breakpoint()`_ function added in Python 3.7.\nSet environment variable ``PYTHONBREAKPOINT=\"web_pdb.set_trace\"`` to launch Web-PDB\nwith ``breakpoint()``.\n\nAdditionally, Web-PDB provides ``catch_post_mortem`` context manager that can catch\nunhandled exceptions raised within its scope and automatically start PDB post-mortem debugging session.\nFor example:\n\n.. code-block:: python\n\n import web_pdb\n\n with web_pdb.catch_post_mortem():\n # Some error-prone code\n assert foo == bar, 'Oops!'\n\nFor more detailed info about the Web-PDB API read docstrings in the ``./web_pdb/__init__.py`` file.\n\nThe ``inspect`` Command\n-----------------------\n\nWeb-PDB provides ``inspect`` or ``i`` command that is not present in the original PDB.\nThis command outputs the list of object's members along with their values.\nSyntax: ``inspect <object_name>`` or ``i <object_name>``.\n\nSpecial members with names enclosed in double underscores (``__``) are ignored.\n\nConsiderations for Multithreading and Multiprocessing Programs\n==============================================================\nMultithreading\n--------------\n\nWeb-PDB maintains one debugger instance that traces only one thread. You should not call ``set_trace()``\nfrom different threads to avoid race conditions. Each thread needs to be debugged separately one at a time.\n\nMultiprocessing\n---------------\n\nEach process can have its own debugger instance provided you call ``set_trace`` with a different port value\nfor each process. This way you can debug each process in a separate browser tab/window.\nTo simplify this you can use ``set_trace(port=-1)`` to select a random port between 32768 and 65536.\n\nCompatibility\n=============\n\n- **Python**: 3.6+\n- **Browsers**: Firefox, Chrome (all modern browsers should work)\n\nLicense\n=======\n\nMIT, see ``LICENSE.txt``.\n\nThe debugger icon made by `Freepik`_ from `www.flaticon.com`_ is licensed by `CC 3.0 BY`_.\n\n.. _PDB: https://docs.python.org/3.6/library/pdb.html\n.. _Bootstrap: http://getbootstrap.com\n.. _Prism: http://prismjs.com/\n.. _Freepik: http://www.freepik.com\n.. _www.flaticon.com: http://www.flaticon.com\n.. _CC 3.0 BY: http://creativecommons.org/licenses/by/3.0/\n.. _breakpoint(): https://docs.python.org/3/library/functions.html#breakpoint\n",
"bugtrack_url": null,
"license": "MIT License",
"summary": "Web interface for Python's built-in PDB debugger",
"version": "1.6.2",
"project_urls": {
"Homepage": "https://github.com/romanvm/python-web-pdb"
},
"split_keywords": [
"pdb",
"remote",
"web",
"debugger'"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "1b367469259d68408b35fe0623851d540f9b98522961ff9d8363e7a70c89d37b",
"md5": "bc802aa743e280a772bb903cf1d60e73",
"sha256": "93d7e307e0e41ea316c7f570f167a0a2e544f4a84163f0b5d55eaa7f92078af3"
},
"downloads": -1,
"filename": "web_pdb-1.6.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bc802aa743e280a772bb903cf1d60e73",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 204459,
"upload_time": "2023-07-06T19:52:26",
"upload_time_iso_8601": "2023-07-06T19:52:26.614173Z",
"url": "https://files.pythonhosted.org/packages/1b/36/7469259d68408b35fe0623851d540f9b98522961ff9d8363e7a70c89d37b/web_pdb-1.6.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "168e047b90ef574d76b550d3874d0888eadd6f7749114c49708e4eebd6a0d02d",
"md5": "8c092c6831ba31f109904529691764cf",
"sha256": "f077221439fe547cf94c0e092afe0afcb5b6c12e8f18e76840e5cf54a9137deb"
},
"downloads": -1,
"filename": "web-pdb-1.6.2.tar.gz",
"has_sig": false,
"md5_digest": "8c092c6831ba31f109904529691764cf",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 211905,
"upload_time": "2023-07-06T19:52:28",
"upload_time_iso_8601": "2023-07-06T19:52:28.533458Z",
"url": "https://files.pythonhosted.org/packages/16/8e/047b90ef574d76b550d3874d0888eadd6f7749114c49708e4eebd6a0d02d/web-pdb-1.6.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-07-06 19:52:28",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "romanvm",
"github_project": "python-web-pdb",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "web-pdb"
}