PEP 553 - built-in debug()

pep-0553.rst

@@ -0,0 +1,144 @@
+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: