[Python-Dev] PEP 553 V2 - builtin breakpoint() (was Re: PEP 553: Built-in debug()) (original) (raw)

Barry Warsaw barry at python.org
Thu Sep 7 14:43:41 EDT 2017

Thanks for all the great feedback folks! Here then is PEP 553 version 2. The notable changes are:

https://www.python.org/dev/peps/pep-0553/

Included below for convenience.

Cheers, -Barry

PEP: 553 Title: Built-in breakpoint() Author: Barry Warsaw <barry at python.org> Status: Draft Type: Standards Track Content-Type: text/x-rst Created: 2017-09-05 Python-Version: 3.7 Post-History: 2017-09-05, 2017-09-07

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 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.

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 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__ then stashes the default value of sys.breakpointhook() to make it easy to reset. This exactly models the existing sys.displayhook() / sys.__displayhook__ and sys.excepthook() / sys.__excepthook__ hooks [3]_.

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(). Since sys.breakpointhook() by default calls pdb.set_trace() by default it accepts no arguments.

Open issues

Confirmation from other debugger vendors

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.

Breakpoint bytecode

Related, there has been an idea to add a bytecode that calls sys.breakpointhook(). Whether built-in breakpoint() emits this bytecode (or gets peephole optimized to the bytecode) is an open issue. The bytecode is useful for debuggers that actively modify bytecode streams to trampoline into their own debugger. Having a "breakpoint" bytecode might allow them to avoid bytecode modification in order to invoke this trampoline. NOTE: It probably makes sense to split this idea into a separate PEP.

Environment variable

Should we add an environment variable so that sys.breakpointhook() can be set outside of the Python invocation? E.g.::

$ export PYTHONBREAKPOINTHOOK=my.debugger:Debugger

This would provide execution environments such as IDEs which run Python code inside them, to set an internal breakpoint hook before any Python code executes.

Call a fancier object by default

Some folks want to be able to use other pdb interfaces such as pdb.pm(). Although this is a less commonly used API, it could be supported by binding sys.breakpointhook to an object that implements __call__(). Calling this object would call pdb.set_trace(), but the object could expose other methods, such as pdb.pm(), making invocation of it as handy as breakpoint.pm().

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.

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

straight through to sys.breakpointhook().

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] https://github.com/python/cpython/pull/3355

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:

More information about the Python-Dev mailing list