Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Misleading documentation of ! prefix in pdb #104301

Closed
SnoopJ opened this issue May 8, 2023 · 2 comments · Fixed by #104342
Closed

Misleading documentation of ! prefix in pdb #104301

SnoopJ opened this issue May 8, 2023 · 2 comments · Fixed by #104342
Assignees
Labels
docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error

Comments

@SnoopJ
Copy link
Contributor

SnoopJ commented May 8, 2023

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

@SnoopJ SnoopJ added the docs Documentation in the Doc dir label May 8, 2023
@gaogaotiantian gaogaotiantian self-assigned this May 9, 2023
@gaogaotiantian
Copy link
Member

gaogaotiantian commented May 9, 2023

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).

@gaogaotiantian gaogaotiantian added the type-bug An unexpected behavior, bug, or error label May 9, 2023
@SnoopJ
Copy link
Contributor Author

SnoopJ commented May 9, 2023

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)

carljm added a commit to carljm/cpython that referenced this issue May 12, 2023
* main:
  pythongh-91896: Fixup some docs issues following ByteString deprecation (python#104422)
  pythonGH-104371: check return value of calling `mv.release` (python#104417)
  pythongh-104415: Fix refleak tests for `typing.ByteString` deprecation (python#104416)
  pythonGH-86275: Implementation of hypothesis stubs for property-based tests, with zoneinfo tests (python#22863)
  pythonGH-103082: Filter LINE events in VM, to simplify tool implementation. (pythonGH-104387)
  pythongh-93649: Split gc- and allocation tests from _testcapimodule.c (pythonGH-104403)
  pythongh-104389: Add 'unused' keyword to Argument Clinic C converters (python#104390)
  pythongh-101819: Prepare _io._IOBase for module state (python#104386)
  pythongh-104413: Fix refleak when super attribute throws AttributeError (python#104414)
  Fix refleak in `super_descr_get` (python#104408)
  pythongh-87526: Remove dead initialization from _zoneinfo parse_abbr() (python#24700)
  pythongh-91896: Improve visibility of `ByteString` deprecation warnings (python#104294)
  pythongh-104371: Fix calls to `__release_buffer__` while an exception is active (python#104378)
  pythongh-104377: fix cell in comprehension that is free in outer scope (python#104394)
  pythongh-104392: Remove _paramspec_tvars from typing (python#104393)
  pythongh-104396: uuid.py to skip platform check for emscripten and wasi (pythongh-104397)
  pythongh-99108: Refresh HACL* from upstream (python#104401)
  pythongh-104301: Allow leading whitespace in disambiguated pdb statements (python#104342)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
docs Documentation in the Doc dir type-bug An unexpected behavior, bug, or error
Projects
None yet
2 participants