From 2833cb48ce284806b65132734f37bba1c7c8e021 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Wed, 6 Sep 2017 09:50:56 -0700 Subject: [PATCH] Guido prefers built-in breakpoint(). --- pep-0553.rst | 71 ++++++++++++++++++++++++++++------------------------ 1 file changed, 38 insertions(+), 33 deletions(-) diff --git a/pep-0553.rst b/pep-0553.rst index d5c0d5d5c..d392369de 100644 --- a/pep-0553.rst +++ b/pep-0553.rst @@ -1,5 +1,5 @@ PEP: 553 -Title: Built-in debug() +Title: Built-in breakpoint() Author: Barry Warsaw Status: Draft Type: Standards Track @@ -12,7 +12,7 @@ Post-History: Abstract ======== -This PEP proposes adding a new built-in function called ``debug()`` which +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. @@ -53,49 +53,53 @@ 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:: +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() - debug() + breakpoint() bar() -Built-in ``debug()`` takes no arguments. +Built-in ``breakpoint()`` 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]_. +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]_. -``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. +``sys.breakpointhook()`` would be called with no arguments. It +returns whatever is returned from the underlying debugger entry point. +``breakpoint()`` returns whatever ``sys.breakpointhook()`` 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 (e.g. PyCharm) that the hooks provided in this PEP will +be useful to them. Related, there has been an idea to add a bytecode that calls -``sys.debughook()``. Whether built-in ``debug()`` 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 "debug" bytecode might allow them to avoid -bytecode modification in order to invoke this trampoline. +``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. Does it make sense to define the built-in function's signature as -``debug(*args, **kws)`` which would just be passed along to the -``sys.debughook()``? One argument for doing this is that it would allow users -to pass useful arguments to their actual debugger. This isn't useful for -``pdb`` but might be useful for alternatives. +``breakpoint(*args, **kws)`` which would just be passed along to the +``sys.breakpointhook()``? One argument for doing this is that it +would allow users to pass useful arguments to their actual debugger. +This isn't useful for ``pdb`` but might be useful for alternatives. Implementation @@ -127,14 +131,15 @@ existing keyword such as ``break here``. This is rejected on several fronts. no existing code (since any existing module global would just shadow the built-in) and is quite easy to implement. -sys.debug() ------------ -Why not ``sys.debug()``? Requiring an import to invoke the debugger is +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.debug() + import sys; sys.breakpoint() which inherits several of the problems this PEP aims to solve.