302 lines
10 KiB
ReStructuredText
302 lines
10 KiB
ReStructuredText
PEP: 553
|
||
Title: Built-in breakpoint()
|
||
Author: Barry Warsaw <barry@python.org>
|
||
Status: Final
|
||
Type: Standards Track
|
||
Content-Type: text/x-rst
|
||
Created: 2017-09-05
|
||
Python-Version: 3.7
|
||
Post-History: 2017-09-05, 2017-09-07, 2017-09-13
|
||
Resolution: https://mail.python.org/pipermail/python-dev/2017-October/149705.html
|
||
|
||
|
||
Abstract
|
||
========
|
||
|
||
This PEP proposes adding a new built-in function called ``breakpoint()`` which
|
||
enters a Python debugger at the point of the call. Additionally, two new
|
||
names are added to the ``sys`` module to make the choice of which debugger is
|
||
entered configurable.
|
||
|
||
|
||
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 [linters]_) complain about this line because it
|
||
contains two statements. Breaking the idiom up into two lines complicates
|
||
its use because there are more opportunities for mistakes at clean up time.
|
||
I.e. you might forget to delete one of those lines when you no longer need
|
||
to debug the code.
|
||
|
||
Python developers also have many other debuggers to choose from, but
|
||
remembering how to invoke them can be problematic. For example, even when
|
||
IDEs have user interface for setting breakpoints, it may still be more
|
||
convenient to just edit the code. The APIs for entering the debugger
|
||
programmatically are inconsistent, so it can be difficult to remember exactly
|
||
what to type.
|
||
|
||
We can solve all these problems by providing a universal API for entering the
|
||
debugger, as proposed in this PEP.
|
||
|
||
|
||
Proposal
|
||
========
|
||
|
||
The JavaScript language provides a ``debugger`` statement [js-debugger]_ which enters
|
||
the debugger at the point where the statement appears.
|
||
|
||
This PEP proposes a new built-in function called ``breakpoint()``
|
||
which enters a Python debugger at the call site. Thus the example
|
||
above would be written like so::
|
||
|
||
foo()
|
||
breakpoint()
|
||
bar()
|
||
|
||
Further, this PEP proposes two new name bindings for the ``sys``
|
||
module, called ``sys.breakpointhook()`` and
|
||
``sys.__breakpointhook__``. By default, ``sys.breakpointhook()``
|
||
implements the actual importing and entry into ``pdb.set_trace()``,
|
||
and it can be set to a different function to change the debugger that
|
||
``breakpoint()`` enters.
|
||
|
||
``sys.__breakpointhook__`` is initialized to the same function as
|
||
``sys.breakpointhook()`` so that you can always easily reset
|
||
``sys.breakpointhook()`` to the default value (e.g. by doing
|
||
``sys.breakpointhook = sys.__breakpointhook__``). This is exactly the same as
|
||
how the existing ``sys.displayhook()`` / ``sys.__displayhook__`` and
|
||
``sys.excepthook()`` / ``sys.__excepthook__`` work [hooks]_.
|
||
|
||
The signature of the built-in is ``breakpoint(*args, **kws)``. The positional
|
||
and keyword arguments are passed straight through to ``sys.breakpointhook()``
|
||
and the signatures must match or a ``TypeError`` will be raised. The return
|
||
from ``sys.breakpointhook()`` is passed back up to, and returned from
|
||
``breakpoint()``.
|
||
|
||
The rationale for this is based on the observation that the underlying
|
||
debuggers may accept additional optional arguments. For example, IPython
|
||
allows you to specify a string that gets printed when the break point is
|
||
entered [ipython-embed]_. As of Python 3.7, the pdb module also supports an
|
||
optional ``header`` argument [pdb-header]_.
|
||
|
||
|
||
Environment variable
|
||
====================
|
||
|
||
The default implementation of ``sys.breakpointhook()`` consults a new
|
||
environment variable called ``PYTHONBREAKPOINT``. This environment variable
|
||
can have various values:
|
||
|
||
* ``PYTHONBREAKPOINT=0`` disables debugging. Specifically, with this value
|
||
``sys.breakpointhook()`` returns ``None`` immediately.
|
||
|
||
* ``PYTHONBREAKPOINT=`` (i.e. the empty string). This is the same as not
|
||
setting the environment variable at all, in which case ``pdb.set_trace()``
|
||
is run as usual.
|
||
|
||
* ``PYTHONBREAKPOINT=some.importable.callable``. In this case,
|
||
``sys.breakpointhook()`` imports the ``some.importable`` module and gets the
|
||
``callable`` object from the resulting module, which it then calls. The
|
||
value may be a string with no dots, in which case it names a built-in
|
||
callable, e.g. ``PYTHONBREAKPOINT=int``. (Guido has expressed the
|
||
preference for normal Python dotted-paths, not setuptools-style entry point
|
||
syntax [syntax]_.)
|
||
|
||
This environment variable allows external processes to control how breakpoints
|
||
are handled. Some uses cases include:
|
||
|
||
* Completely disabling all accidental ``breakpoint()`` calls pushed to
|
||
production. This could be accomplished by setting ``PYTHONBREAKPOINT=0`` in
|
||
the execution environment. Another suggestion by reviewers of the PEP was
|
||
to set ``PYTHONBREAKPOINT=sys.exit`` in this case.
|
||
|
||
* IDE integration with specialized debuggers for embedded execution. The IDE
|
||
would run the program in its debugging environment with ``PYTHONBREAKPOINT``
|
||
set to their internal debugging hook.
|
||
|
||
``PYTHONBREAKPOINT`` is re-interpreted every time ``sys.breakpointhook()`` is
|
||
reached. This allows processes to change its value during the execution of a
|
||
program and have ``breakpoint()`` respond to those changes. It is not
|
||
considered a performance critical section since entering a debugger by
|
||
definition stops execution. Thus, programs can do the following::
|
||
|
||
os.environ['PYTHONBREAKPOINT'] = 'foo.bar.baz'
|
||
breakpoint() # Imports foo.bar and calls foo.bar.baz()
|
||
|
||
Overriding ``sys.breakpointhook`` defeats the default consultation of
|
||
``PYTHONBREAKPOINT``. It is up to the overriding code to consult
|
||
``PYTHONBREAKPOINT`` if they want.
|
||
|
||
If access to the ``PYTHONBREAKPOINT`` callable fails in any way (e.g. the
|
||
import fails, or the resulting module does not contain the callable), a
|
||
``RuntimeWarning`` is issued, and no breakpoint function is called.
|
||
|
||
Note that as with all other ``PYTHON*`` environment variables,
|
||
``PYTHONBREAKPOINT`` is ignored when the interpreter is started with
|
||
``-E``. This means the default behavior will occur
|
||
(i.e. ``pdb.set_trace()`` will run). There was some discussion about
|
||
alternatively treating ``PYTHONBREAKPOINT=0`` when ``-E`` as in
|
||
effect, but the opinions were inconclusive, so it was decided that
|
||
this wasn't special enough for a special case.
|
||
|
||
|
||
Implementation
|
||
==============
|
||
|
||
A pull request exists with the proposed implementation [impl]_.
|
||
|
||
While the actual implementation is in C, the Python pseudo-code for this
|
||
feature looks roughly like the following::
|
||
|
||
# In builtins.
|
||
def breakpoint(*args, **kws):
|
||
import sys
|
||
missing = object()
|
||
hook = getattr(sys, 'breakpointhook', missing)
|
||
if hook is missing:
|
||
raise RuntimeError('lost sys.breakpointhook')
|
||
return hook(*args, **kws)
|
||
|
||
# In sys.
|
||
def breakpointhook(*args, **kws):
|
||
import importlib, os, warnings
|
||
hookname = os.getenv('PYTHONBREAKPOINT')
|
||
if hookname is None or len(hookname) == 0:
|
||
hookname = 'pdb.set_trace'
|
||
elif hookname == '0':
|
||
return None
|
||
modname, dot, funcname = hookname.rpartition('.')
|
||
if dot == '':
|
||
modname = 'builtins'
|
||
try:
|
||
module = importlib.import_module(modname)
|
||
hook = getattr(module, funcname)
|
||
except:
|
||
warnings.warn(
|
||
'Ignoring unimportable $PYTHONBREAKPOINT: {}'.format(
|
||
hookname),
|
||
RuntimeWarning)
|
||
return None
|
||
return hook(*args, **kws)
|
||
|
||
__breakpointhook__ = breakpointhook
|
||
|
||
|
||
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.
|
||
|
||
|
||
sys.breakpoint()
|
||
----------------
|
||
|
||
Why not ``sys.breakpoint()``? Requiring an import to invoke the debugger is
|
||
explicitly rejected because ``sys`` is not imported in every module. That
|
||
just requires more typing and would lead to::
|
||
|
||
import sys; sys.breakpoint()
|
||
|
||
which inherits several of the problems this PEP aims to solve.
|
||
|
||
|
||
Version History
|
||
===============
|
||
|
||
* 2019-10-13
|
||
|
||
* Add missing ``return None`` in ``except`` clause to pseudo-code.
|
||
|
||
* 2017-09-13
|
||
|
||
* The ``PYTHONBREAKPOINT`` environment variable is made a first class
|
||
feature.
|
||
|
||
* 2017-09-07
|
||
|
||
* ``debug()`` renamed to ``breakpoint()``
|
||
* Signature changed to ``breakpoint(*args, **kws)`` which is passed straight
|
||
through to ``sys.breakpointhook()``.
|
||
|
||
|
||
References
|
||
==========
|
||
|
||
.. [ipython-embed]
|
||
http://ipython.readthedocs.io/en/stable/api/generated/IPython.terminal.embed.html
|
||
|
||
.. [pdb-header]
|
||
https://docs.python.org/3.7/library/pdb.html#pdb.set_trace
|
||
|
||
.. [linters]
|
||
http://flake8.readthedocs.io/en/latest/
|
||
|
||
.. [js-debugger]
|
||
https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/debugger
|
||
|
||
.. [hooks]
|
||
https://docs.python.org/3/library/sys.html#sys.displayhook
|
||
|
||
.. [syntax]
|
||
http://setuptools.readthedocs.io/en/latest/setuptools.html?highlight=console#automatic-script-creation
|
||
|
||
.. [impl]
|
||
https://github.com/python/cpython/pull/3355
|
||
|
||
.. [envar]
|
||
https://mail.python.org/pipermail/python-dev/2017-September/149447.html
|
||
|
||
|
||
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:
|