Misleading documentation of ! prefix in pdb

[SnoopJ]

The documentation for pdb says:

.. pdbcommand:: ! statement                                                           
                                                                                      
   Execute the (one-line) *statement* in the context of the current stack frame.      
   The exclamation point can be omitted unless the first word of the statement        
   resembles a debugger command.  To set a global variable, you can prefix the        
   assignment command with a :keyword:`global` statement on the same line,            
   e.g.::                                                                             
                                                                                      
      (Pdb) global list_options; list_options = ['-l']                                
      (Pdb)

Which suggests that the prefix is used with a space between the ! prefix and the statement to be executed. However, the implementation consumes only the prefix, which means that the natural reading of the docs leads to an IndentationError:

$ python3 test.py 
--Return--
> /home/snoopjedi/repos/cpython/test.py(3)<module>()->None
-> breakpoint()
(Pdb) l
  1     lst = [1, 2, 3]
  2     it = iter(lst)
  3  -> breakpoint()
[EOF]
(Pdb) ! next(it)
*** IndentationError: unexpected indent

while omitting the space gives the intended result:

(Pdb) !next(it)
1

It would also be helpful to have an example in the documentation that actually uses the prefix for first-word disambiguation as described in the text.

Linked PRs

• gh-104301: Tidy pdb documentation of exclamation prefix #104302
• gh-104301: Allow leading whitespace in disambiguated pdb statements #104342

[gaogaotiantian]

I actually consider this as a bug, or at least a feature request. It does not make much sense to forbid users to add spaces after !. I can't think of a single use case for that. So instead of changing the logs, how about we just fix the behavior?

Adding an example for the explanation of why ! is needed is good. Not sure if next is the best candidate. Maybe something like ! n=2 makes more sense? However, pdb will generate an error on cases like this after #103464 is merged. Now that 3.12 beta release is pushed, we have a chance for this to be merged in. So the example would be slightly less critical(still good).

[SnoopJ]

I actually consider this a bug, or at least a feature request. It does not make much sense to forbid users to add spaces after !. I can think of a single use case for that. So instead of changing the logs, how about we just fix the behavior?

I'm inclined to agree that the whitespace could just be allowed, and it seems easy to support as-documented. I like the suggestion to use an assignment as the example case in place of next, thanks, will put together a separate PR (edit: see #104342)