145 lines
4.2 KiB
ReStructuredText
145 lines
4.2 KiB
ReStructuredText
PEP: 553
|
||
Title: Built-in debug()
|
||
Author: Barry Warsaw <barry@python.org>
|
||
Status: Draft
|
||
Type: Standards Track
|
||
Content-Type: text/x-rst
|
||
Created: 2017-09-05
|
||
Python-Version: 3.7
|
||
Post-History:
|
||
|
||
|
||
Abstract
|
||
========
|
||
|
||
This PEP proposes adding a new built-in function called ``debug()`` which
|
||
enters a Python debugger at the point of the call. Additionally, two new
|
||
names are added to the ``sys`` module to make the debugger pluggable.
|
||
|
||
|
||
Rationale
|
||
=========
|
||
|
||
Python has long had a great debugger in its standard library called ``pdb``.
|
||
Setting a break point is commonly written like this::
|
||
|
||
foo()
|
||
import pdb; pdb.set_trace()
|
||
bar()
|
||
|
||
Thus after executing ``foo()`` and before executing ``bar()``, Python will
|
||
enter the debugger. However this idiom has several disadvantages.
|
||
|
||
* It's a lot to type (27 characters).
|
||
|
||
* It's easy to typo. The PEP author often mistypes this line, e.g. omitting
|
||
the semicolon, or typing a dot instead of an underscore.
|
||
|
||
* It ties debugging directly to the choice of pdb. There might be other
|
||
debugging options, say if you're using an IDE or some other development
|
||
environment.
|
||
|
||
* Python linters (e.g. flake8 [1]_) complain about this line because it
|
||
contains two statements. Breaking the idiom up into two lines further
|
||
complicates the use of the debugger,
|
||
|
||
These problems can be solved by modeling a solution based on prior art in
|
||
other languages, and utilizing a convention that already exists in Python.
|
||
|
||
|
||
Proposal
|
||
========
|
||
|
||
The JavaScript language provides a ``debugger`` statement [2]_ which enters
|
||
the debugger at the point where the statement appears.
|
||
|
||
This PEP proposes a new built-in function called ``debug()`` which enters a
|
||
Python debugger at the call site. Thus the example above would be written
|
||
like so::
|
||
|
||
foo()
|
||
debug()
|
||
bar()
|
||
|
||
Built-in ``debug()`` takes no arguments.
|
||
|
||
Further, this PEP proposes two new name bindings for the ``sys`` module,
|
||
called ``debughook()`` and ``__debughook__``. By default, ``sys.debughook()``
|
||
implements the actual importing and entry into ``pdb.set_trace()``, and it can
|
||
be set to a different function to change the debugger that ``debug()`` enters.
|
||
``sys.__debughook__`` then stashes the default value of ``sys.debughook()`` to
|
||
make it easy to reset. This exactly models the existing ``sys.displayhook()``
|
||
/ ``sys.__displayhook__`` and ``sys.excepthook()`` / ``sys.__excepthook__``
|
||
hooks [3]_.
|
||
|
||
``sys.displayhook()`` would be called with no arguments. It returns whatever
|
||
is returned from the underlying debugger entry point. ``debug()`` returns
|
||
whatever ``sys.displayhook()`` returns.
|
||
|
||
|
||
Open issues
|
||
===========
|
||
|
||
We want to get confirmation from at least one alternative debugger
|
||
implementation (e.g. PyCharm) that the hooks provided in this PEP will be
|
||
useful to them.
|
||
|
||
|
||
Implementation
|
||
==============
|
||
|
||
A pull request exists with the proposed implementation [4]_.
|
||
|
||
|
||
Rejected alternatives
|
||
=====================
|
||
|
||
A new keyword
|
||
-------------
|
||
|
||
Originally, the author considered a new keyword, or an extension to an
|
||
existing keyword such as ``break here``. This is rejected on several fronts.
|
||
|
||
* A brand new keyword would require a ``__future__`` to enable it since almost
|
||
any new keyword could conflict with existing code. This negates the ease
|
||
with which you can enter the debugger.
|
||
|
||
* An extended keyword such as ``break here``, while more readable and not
|
||
requiring a ``__future__`` would tie the keyword extension to this new
|
||
feature, preventing more useful extensions such as those proposed in
|
||
PEP 548.
|
||
|
||
* A new keyword would require a modified grammar and likely a new bytecode.
|
||
Each of these makes the implementation more complex. A new built-in breaks
|
||
no existing code (since any existing module global would just shadow the
|
||
built-in) and is quite easy to implement.
|
||
|
||
|
||
References
|
||
==========
|
||
|
||
.. [1] http://flake8.readthedocs.io/en/latest/
|
||
|
||
.. [2] https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger
|
||
|
||
.. [3] https://docs.python.org/3/library/sys.html#sys.displayhook
|
||
|
||
.. [4] XXX
|
||
|
||
|
||
Copyright
|
||
=========
|
||
|
||
This document has been placed in the public domain.
|
||
|
||
|
||
|
||
..
|
||
Local Variables:
|
||
mode: indented-text
|
||
indent-tabs-mode: nil
|
||
sentence-end-double-space: t
|
||
fill-column: 70
|
||
coding: utf-8
|
||
End:
|