diff options
Diffstat (limited to 'Doc/library/sys.rst')
| -rw-r--r-- | Doc/library/sys.rst | 47 |
1 files changed, 43 insertions, 4 deletions
diff --git a/Doc/library/sys.rst b/Doc/library/sys.rst index 85f31368c3..aa7bd477b0 100644 --- a/Doc/library/sys.rst +++ b/Doc/library/sys.rst @@ -109,6 +109,40 @@ 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()``. + + The default implementation first consults the environment variable + :envvar:`PYTHONBREAKPOINT`. If that is set to ``"0"`` then this function + returns immediately; i.e. it is a no-op. If the environment variable is + not set, or is set to the empty string, ``pdb.set_trace()`` is called. + Otherwise this variable should name a function to run, using Python's + dotted-import nomenclature, e.g. ``package.subpackage.module.function``. + In this case, ``package.subpackage.module`` would be imported and the + resulting module must have a callable named ``function()``. This is run, + passing in ``*args`` and ``**kws``, and whatever ``function()`` returns, + ``sys.breakpointhook()`` returns to the built-in :func:`breakpoint` + function. + + Note that if anything goes wrong while importing the callable named by + :envvar:`PYTHONBREAKPOINT`, a :exc:`RuntimeWarning` is reported and the + breakpoint is ignored. + + Also note that if ``sys.breakpointhook()`` is overridden programmatically, + :envvar:`PYTHONBREAKPOINT` is *not* consulted. + + .. versionadded:: 3.7 + .. function:: _debugmallocstats() Print low-level information to stderr about the state of CPython's memory @@ -187,14 +221,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() |