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.
Important Notice
================
Currently this project is in a minimum maintenance mode.
It means that I will try to maintain compatibility with new Python versions and address
critical issues, if any arise. But at the moment I have no time or resources to develop
new features or properly review external contributions. That is why only pull requests
with bug fixes will be prioritized. Other issues or pull requests may or may not be reviewed or accepted.
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": null,
"docs_url": null,
"requires_python": ">=3.6",
"maintainer_email": null,
"keywords": "pdb remote web debugger'",
"author": "Roman Miroshnychenko",
"author_email": "roman1972@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/df/1e/650ca20a67831268a24d06a420022b7183cd284b1e49384d03565f2b4d39/web-pdb-1.6.3.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\nImportant Notice\n================\n\nCurrently this project is in a minimum maintenance mode.\nIt means that I will try to maintain compatibility with new Python versions and address\ncritical issues, if any arise. But at the moment I have no time or resources to develop\nnew features or properly review external contributions. That is why only pull requests\nwith bug fixes will be prioritized. Other issues or pull requests may or may not be reviewed or accepted.\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.3",
"project_urls": {
"Homepage": "https://github.com/romanvm/python-web-pdb"
},
"split_keywords": [
"pdb",
"remote",
"web",
"debugger'"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6f8863d237b69dd2b60dd72d63515c46b640daf069e4755c5f6a84809f753aeb",
"md5": "58b0630a4cf34dc2a383c745eeb1d430",
"sha256": "9fd8dd7ff0ac3869b216454c651812194c4592ffcdc6bd2ec78fb07d50224171"
},
"downloads": -1,
"filename": "web_pdb-1.6.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "58b0630a4cf34dc2a383c745eeb1d430",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.6",
"size": 205579,
"upload_time": "2024-11-16T18:13:50",
"upload_time_iso_8601": "2024-11-16T18:13:50.574421Z",
"url": "https://files.pythonhosted.org/packages/6f/88/63d237b69dd2b60dd72d63515c46b640daf069e4755c5f6a84809f753aeb/web_pdb-1.6.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "df1e650ca20a67831268a24d06a420022b7183cd284b1e49384d03565f2b4d39",
"md5": "5ddc4948209bfaecd2c232c223da6423",
"sha256": "cc8169d5b0edfd6090029bc7452a2928786dbcad9dc9f228e8eb45351b88f6e9"
},
"downloads": -1,
"filename": "web-pdb-1.6.3.tar.gz",
"has_sig": false,
"md5_digest": "5ddc4948209bfaecd2c232c223da6423",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.6",
"size": 212521,
"upload_time": "2024-11-16T18:13:52",
"upload_time_iso_8601": "2024-11-16T18:13:52.394402Z",
"url": "https://files.pythonhosted.org/packages/df/1e/650ca20a67831268a24d06a420022b7183cd284b1e49384d03565f2b4d39/web-pdb-1.6.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-16 18:13:52",
"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"
}
JSON
