Misleading documentation of `!` prefix in `pdb` #104301

SnoopJ · 2023-05-08T19:08:36Z

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

The text was updated successfully, but these errors were encountered:

gaogaotiantian · 2023-05-09T04:25:50Z

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 · 2023-05-09T04:40:03Z

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)

SnoopJ added the docs Documentation in the Doc dir label May 8, 2023

SnoopJ linked a pull request May 8, 2023 that will close this issue

gh-104301: Tidy pdb documentation of exclamation prefix #104302

Open

gaogaotiantian self-assigned this May 9, 2023

gaogaotiantian added the type-bug An unexpected behavior, bug, or error label May 9, 2023

SnoopJ linked a pull request May 9, 2023 that will close this issue

gh-104301: Allow leading whitespace in disambiguated pdb statements #104342

Open

Misleading documentation of `!` prefix in `pdb` #104301

Misleading documentation of `!` prefix in `pdb` #104301

SnoopJ commented May 8, 2023 •

edited by bedevere-bot

gaogaotiantian commented May 9, 2023 •

edited

SnoopJ commented May 9, 2023 •

edited

Misleading documentation of ! prefix in pdb #104301

Misleading documentation of ! prefix in pdb #104301

Comments

SnoopJ commented May 8, 2023 • edited by bedevere-bot

Linked PRs

gaogaotiantian commented May 9, 2023 • edited

SnoopJ commented May 9, 2023 • edited

Misleading documentation of `!` prefix in `pdb` #104301

Misleading documentation of `!` prefix in `pdb` #104301

SnoopJ commented May 8, 2023 •

edited by bedevere-bot

gaogaotiantian commented May 9, 2023 •

edited

SnoopJ commented May 9, 2023 •

edited