warsaw · Oct 5, 2017 · Aug 30, 2017 · Sep 4, 2017 · Sep 4, 2017 · Sep 4, 2017
diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst
@@ -7,24 +7,24 @@ Built-in Functions
 The Python interpreter has a number of functions and types built into it that
 are always available.  They are listed here in alphabetical order.
 
-===================  =================  ==================  ================  ====================
-..                   ..                 Built-in Functions  ..                ..
-===================  =================  ==================  ================  ====================
-:func:`abs`          |func-dict|_       :func:`help`        :func:`min`       :func:`setattr`
-:func:`all`          :func:`dir`        :func:`hex`         :func:`next`      :func:`slice`
-:func:`any`          :func:`divmod`     :func:`id`          :func:`object`    :func:`sorted`
-:func:`ascii`        :func:`enumerate`  :func:`input`       :func:`oct`       :func:`staticmethod`
-:func:`bin`          :func:`eval`       :func:`int`         :func:`open`      |func-str|_
-:func:`bool`         :func:`exec`       :func:`isinstance`  :func:`ord`       :func:`sum`
-|func-bytearray|_    :func:`filter`     :func:`issubclass`  :func:`pow`       :func:`super`
-|func-bytes|_        :func:`float`      :func:`iter`        :func:`print`     |func-tuple|_
-:func:`callable`     :func:`format`     :func:`len`         :func:`property`  :func:`type`
-:func:`chr`          |func-frozenset|_  |func-list|_        |func-range|_     :func:`vars`
-:func:`classmethod`  :func:`getattr`    :func:`locals`      :func:`repr`      :func:`zip`
-:func:`compile`      :func:`globals`    :func:`map`         :func:`reversed`  :func:`__import__`
+===================  =================  ==================  ==================  ====================
+..                   ..                 Built-in Functions  ..                  ..
+===================  =================  ==================  ==================  ====================
+:func:`abs`          :func:`delattr`    :func:`hash`        |func-memoryview|_  |func-set|_
+:func:`all`          |func-dict|_       :func:`help`        :func:`min`         :func:`setattr`
+:func:`any`          :func:`dir`        :func:`hex`         :func:`next`        :func:`slice`
+:func:`ascii`        :func:`divmod`     :func:`id`          :func:`object`      :func:`sorted`
+:func:`bin`          :func:`enumerate`  :func:`input`       :func:`oct`         :func:`staticmethod`
+:func:`bool`         :func:`eval`       :func:`int`         :func:`open`        |func-str|_
+:func:`breakpoint`   :func:`exec`       :func:`isinstance`  :func:`ord`         :func:`sum`
+|func-bytearray|_    :func:`filter`     :func:`issubclass`  :func:`pow`         :func:`super`
+|func-bytes|_        :func:`float`      :func:`iter`        :func:`print`       |func-tuple|_
+:func:`callable`     :func:`format`     :func:`len`         :func:`property`    :func:`type`
+:func:`chr`          |func-frozenset|_  |func-list|_        |func-range|_       :func:`vars`
+:func:`classmethod`  :func:`getattr`    :func:`locals`      :func:`repr`        :func:`zip`
+:func:`compile`      :func:`globals`    :func:`map`         :func:`reversed`    :func:`__import__`
 :func:`complex`      :func:`hasattr`    :func:`max`         :func:`round`
-:func:`delattr`      :func:`hash`       |func-memoryview|_  |func-set|_
-===================  =================  ==================  ================  ====================
+===================  =================  ==================  ==================  ====================
 
 .. using :func:`dict` would create a link to another page, so local targets are
    used, with replacement texts to make the output in the table consistent
@@ -113,6 +113,20 @@ are always available.  They are listed here in alphabetical order.
    .. index:: pair: Boolean; type
 
 
+.. function:: breakpoint(*args, **kws)
+
+   This function drops you into the debugger at the call site.  Specifically,
+   it calls :func:`sys.breakpointhook`, passing ``args`` and ``kws`` straight
+   through.  By default, ``sys.breakpointhook()`` calls
+   :func:`pdb.set_trace()` expecting no arguments.  In this case, it is
+   purely a convenience function so you don't have to explicitly import
+   :mod:`pdb` or type as much code to enter the debugger.  However,
+   :func:`sys.breakpointhook` can be set to some other function and
+   :func:`breakpoint` will automatically call that, allowing you to drop into
+   the debugger of choice.
+
+   .. versionadded:: 3.7
+
 .. _func-bytearray:
 .. class:: bytearray([source[, encoding[, errors]]])
    :noindex:

diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst
@@ -109,6 +109,21 @@ always available.
    This function should be used for internal and specialized purposes only.
 
 
+.. function:: breakpointhook()
+
+   This hook function is called by built-in :func:`breakpoint`.  By default,
+   it drops you into the :mod:`pdb` debugger, but it can be set to any other
+   function so that you can choose which debugger gets used.
+
+   The signature of this function is dependent on what it calls.  For example,
+   the default binding (e.g. ``pdb.set_trace()``) expects no arguments, but
+   you might bind it to a function that expects additional arguments
+   (positional and/or keyword).  The built-in ``breakpoint()`` function passes
+   its ``*args`` and ``**kws`` straight through.  Whatever
+   ``breakpointhooks()`` returns is returned from ``breakpoint()``.
+
+   .. versionadded:: 3.7
+
 .. function:: _debugmallocstats()
 
    Print low-level information to stderr about the state of CPython's memory
@@ -187,14 +202,19 @@ always available.
    customized by assigning another three-argument function to ``sys.excepthook``.
 
 
-.. data:: __displayhook__
+.. data:: __breakpointhook__
+          __displayhook__
           __excepthook__
 
-   These objects contain the original values of ``displayhook`` and ``excepthook``
-   at the start of the program.  They are saved so that ``displayhook`` and
-   ``excepthook`` can be restored in case they happen to get replaced with broken
+   These objects contain the original values of ``breakpointhook``,
+   ``displayhook``, and ``excepthook`` at the start of the program.  They are
+   saved so that ``breakpointhook``, ``displayhook`` and ``excepthook`` can be
+   restored in case they happen to get replaced with broken or alternative
    objects.
 
+   .. versionadded:: 3.7
+      __breakpointhook__
+
 
 .. function:: exc_info()
 

diff --git a/Lib/test/test_builtin.py b/Lib/test/test_builtin.py
@@ -20,6 +20,7 @@
 from operator import neg
 from test.support import TESTFN, unlink, check_warnings
 from test.support.script_helper import assert_python_ok
+from unittest.mock import patch
 try:
     import pty, signal
 except ImportError:
@@ -352,6 +353,59 @@ def f(): """doc"""
                 rv = ns['f']()
                 self.assertEqual(rv, (debugval, docstring))
 
+    def test_breakpoint(self):
+        with patch('pdb.set_trace') as mock:
+            breakpoint()
+        mock.assert_called_once()
+
+    def test_breakpoint_with_breakpointhook_set(self):
+        call_status = 'Not called'
+        def my_breakpointhook():
+            nonlocal call_status
+            call_status = 'Called'
+        try:
+            sys.breakpointhook = my_breakpointhook
+            breakpoint()
+        finally:
+            sys.breakpointhook = sys.__breakpointhook__
+        self.assertEqual(call_status, 'Called')
+
+    def test_breakpoint_with_breakpointhook_reset(self):
+        call_status = 'Not called'
+        def my_breakpointhook():
+            nonlocal call_status
+            call_status = 'Called'
+        try:
+            sys.breakpointhook = my_breakpointhook
+            breakpoint()
+        finally:
+            sys.breakpointhook = sys.__breakpointhook__
+        self.assertEqual(call_status, 'Called')
+        with patch('pdb.set_trace') as mock:
+            breakpoint()
+        mock.assert_called_once()
+
+    def test_breakpoint_with_args_and_keywords(self):
+        call_args = None
+        def my_breakpointhook(*args, **kws):
+            nonlocal call_args
+            call_args = args, kws
+        try:
+            sys.breakpointhook = my_breakpointhook
+            breakpoint(1, 2, 3, four=4, five=5)
+        finally:
+            sys.breakpointhook = sys.__breakpointhook__
+        self.assertEqual(call_args, ((1, 2, 3), dict(four=4, five=5)))
+
+    def test_breakpoint_with_passthru_error(self):
+        def my_breakpointhook():
+            pass
+        try:
+            sys.breakpointhook = my_breakpointhook
+            self.assertRaises(TypeError, breakpoint, 1, 2, 3, four=4, five=5)
+        finally:
+            sys.breakpointhook = sys.__breakpointhook__
+
     def test_delattr(self):
         sys.spam = 1
         delattr(sys, 'spam')

diff --git a/Lib/test/test_inspect.py b/Lib/test/test_inspect.py
@@ -3523,7 +3523,8 @@ def test_builtins_have_signatures(self):
         needs_semantic_update = {"round"}
         no_signature |= needs_semantic_update
         # These need *args support in Argument Clinic
-        needs_varargs = {"min", "max", "print", "__build_class__"}
+        needs_varargs = {"breakpoint", "min", "max", "print",
+                         "__build_class__"}
         no_signature |= needs_varargs
         # These simply weren't covered in the initial AC conversion
         # for builtin callables

diff --git a/Misc/NEWS.d/next/Core and Builtins/2017-09-05-14-19-02.bpo-31353.oGZUeJ.rst b/Misc/NEWS.d/next/Core and Builtins/2017-09-05-14-19-02.bpo-31353.oGZUeJ.rst
@@ -0,0 +1,5 @@
+PEP 553 - Add a new built-in called ``breakpoint()`` which calls
+``sys.breakpointhook()``.  By default this imports ``pdb`` and calls
+``pdb.set_trace()``, but users may override ``sys.breakpointhook()`` to call
+whatever debugger they want.  The original value of the hook is saved in
+``sys.__breakpointhook__``.
diff --git a/Python/bltinmodule.c b/Python/bltinmodule.c
@@ -415,6 +415,30 @@ builtin_callable(PyObject *module, PyObject *obj)
     return PyBool_FromLong((long)PyCallable_Check(obj));
 }
 
+static PyObject *
+builtin_breakpoint(PyObject *self, PyObject *args, PyObject *keywords)
+{
+    PyObject *hook = PySys_GetObject("breakpointhook");
+    PyObject *retval = NULL;
+
+    if (hook == NULL) {
+        PyErr_SetString(PyExc_RuntimeError, "lost sys.breakpointhook");
+        return NULL;
+    }
+    Py_INCREF(hook);
+    retval = PyObject_Call(hook, args, keywords);
+    Py_DECREF(hook);
+    return retval;
+}
+
+PyDoc_STRVAR(breakpoint_doc,
+"breakpoint(*args, **kws)\n\
+\n\
+Call the sys.breakpointhook() function, passing *args and **kws\n\
+through unchanged.  sys.breakpointhook() must accept the arguments\n\
+passed.\n\
+\n\
+By default, this drops you into the pdb debugger.");
 
 typedef struct {
     PyObject_HEAD
@@ -2620,6 +2644,7 @@ static PyMethodDef builtin_methods[] = {
     BUILTIN_ANY_METHODDEF
     BUILTIN_ASCII_METHODDEF
     BUILTIN_BIN_METHODDEF
+    {"breakpoint",      (PyCFunction)builtin_breakpoint, METH_VARARGS | METH_KEYWORDS, breakpoint_doc},
     BUILTIN_CALLABLE_METHODDEF
     BUILTIN_CHR_METHODDEF
     BUILTIN_COMPILE_METHODDEF

diff --git a/Python/sysmodule.c b/Python/sysmodule.c
@@ -93,6 +93,32 @@ PySys_SetObject(const char *name, PyObject *v)
         return PyDict_SetItemString(sd, name, v);
 }
 
+static PyObject *
+sys_breakpointhook(PyObject *self, PyObject *noargs)
+{
+    PyObject *pdb = PyImport_ImportModule("pdb");
+    PyObject *set_trace = NULL;
+    PyObject *retval = NULL;
+
+    if (pdb == NULL) {
+        return NULL;
+    }
+    set_trace = PyObject_GetAttrString(pdb, "set_trace");
+    Py_DECREF(pdb);
+    if (set_trace == NULL) {
+        return NULL;
+    }
+    retval = PyObject_CallObject(set_trace, NULL);
+    Py_DECREF(set_trace);
+    return retval;
+}
+
+PyDoc_STRVAR(breakpointhook_doc,
+"breakpointhook()\n"
+"\n"
+"Called when the built-in breakpoint() function is called.\n"
+);
+
 /* Write repr(o) to sys.stdout using sys.stdout.encoding and 'backslashreplace'
    error handler. If sys.stdout has a buffer attribute, use
    sys.stdout.buffer.write(encoded), otherwise redecode the string and use
@@ -1360,6 +1386,7 @@ sys_getandroidapilevel(PyObject *self)
 
 static PyMethodDef sys_methods[] = {
     /* Might as well keep this in alphabetic order */
+    {"breakpointhook",  sys_breakpointhook, METH_NOARGS, breakpointhook_doc},
     {"callstats", (PyCFunction)sys_callstats, METH_NOARGS,
      callstats_doc},
     {"_clear_type_cache",       sys_clear_type_cache,     METH_NOARGS,
@@ -1951,6 +1978,9 @@ _PySys_BeginInit(void)
                                PyDict_GetItemString(sysdict, "displayhook"));
     SET_SYS_FROM_STRING_BORROW("__excepthook__",
                                PyDict_GetItemString(sysdict, "excepthook"));
+    SET_SYS_FROM_STRING_BORROW(
+        "__breakpointhook__",
+        PyDict_GetItemString(sysdict, "breakpointhook"));
     SET_SYS_FROM_STRING("version",
                          PyUnicode_FromString(Py_GetVersion()));
     SET_SYS_FROM_STRING("hexversion",