bpo-41510: Updated documentation to add header kw-argument of pdb.set_trace()
#21793
Conversation
| :func:`pdb.set_trace()` expecting an optional keyword argument `header`. 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. |
There was a problem hiding this comment.
I'm not an expert, but I wonder if we can leave those details behind.
| :func:`pdb.set_trace()` expecting an optional keyword argument `header`. 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. | |
| :func:`pdb.set_trace()`, however it can be set to some other function and | |
| :func:`breakpoint` will automatically call that, allowing you to drop into | |
| the debugger of choice. |
There was a problem hiding this comment.
I understand, but if we are providing information about the standard hook then we must provide what behavior it would show (i.e, arguments' info)
| @@ -189,10 +189,10 @@ always available. | |||
| function so that you can choose which debugger gets used. | |||
|
|
|||
| The signature of this function is dependent on what it calls. For example, | |||
There was a problem hiding this comment.
Here also I would suggest dropping that extra information.
| The signature of this function is dependent on what it calls. For example, | |
| The signature of this function is dependent on what it calls. The built-in | |
| ``breakpoint()`` function passes its ``*args`` and ``**kws`` straight through. | |
| Whatever ``breakpointhooks()`` returns is returned from ``breakpoint()``. |
| :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:`pdb.set_trace()` expecting an optional keyword argument `header`. In |
There was a problem hiding this comment.
My eyes may be wrong but there might be an extra space before "In".
There was a problem hiding this comment.
In .rst files I guess there must be 2 spaces after .
There was a problem hiding this comment.
https://devguide.python.org/documenting/#use-of-whitespace
A sentence-ending period may be followed by one or two spaces; while reST ignores the second space, it is customarily put in by some users, for example to aid Emacs’ auto-fill mode.
|
Hi @nanjekyejoannah this can be merged, I guess. |
I'm leaving my feedback as a comment because I don't have really clear feedback.
I wonder if changing the text is necessary, other than maybe a slight rewording because the current text says the default hook won't accept any arguments which is untrue. I wouldn't document the keyword argument of pdb.set_trace here, IMHO that just makes the documentation harder to understand.
Note that the breakpoint function is intended to make it easy to drop in a debugger. I'd expect that most of not all calls to the breakpoint function will have no arguments.
| :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:`pdb.set_trace()` expecting an optional keyword argument `header`. In |
There was a problem hiding this comment.
I'm not a native english speaker, but "expecting an optional ..." doesn't feel right.
I'm not sure if anything needs to change here, expect maybe to rephrase the current text to indicate that the default hook can be called without arguments. Users can look up the documentation of pdb.set_trace for advanced usage.
https://bugs.python.org/issue41510