Make $PYTHONBREAKPOINT a first class feature.

pep-0553.rst

@@ -80,6 +80,56 @@ from ``sys.breakpointhook()`` is passed back up to, and returned from
 ``pdb.set_trace()`` by default it accepts no arguments.
 
 
+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 [4]_ .)
+
+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.  (Of note, the implementation fast-tracks the
+``PYTHONBREAKPOINT=0`` case.)
+
+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.
+
+
 Open issues
 ===========
 
@@ -104,32 +154,6 @@ 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.
-
-If we did add that hook, what should be the default value and should
-it be easy to disable ``breakpoint()``?  The rationale here is calls
-to ``breakpoint()`` that might accidentally sneak into production.
-
-The author's opinion is that if we support this environment variable
-it should be enabled --and point to ``pdb.set_trace()``-- by default.
-This way it Just Works for the average developer.  The maintainers of
-CI, build, or production systems should be able to easily configure
-their environments to disable ``breakpoint()``.  We probably want to
-support a shorthand for "disable built-in breakpoint()", e.g.::
-
-    $ export PYTHONBREAKPOINTHOOK=0
-
-
 Call a fancier object by default
 --------------------------------
 
@@ -144,7 +168,7 @@ it as handy as ``breakpoint.pm()``.
 Implementation
 ==============
 
-A pull request exists with the proposed implementation [4]_.
+A pull request exists with the proposed implementation [5]_.
 
 
 Rejected alternatives
@@ -202,7 +226,9 @@ References
 
 .. [3] https://docs.python.org/3/library/sys.html#sys.displayhook
 
-.. [4] https://github.com/python/cpython/pull/3355
+.. [4] http://setuptools.readthedocs.io/en/latest/setuptools.html?highlight=console#automatic-script-creation
+
+.. [5] https://github.com/python/cpython/pull/3355
 
 
 Copyright