Allow troubleshooting with pdb

[jaraco]

In #9348 (comment), I attempted to use pdb to debug an unhandled exception in pip, but when I did, found that pdb couldn't intercept the exception because pip handles all exceptions.

I suggest that pip should provide an alternate interface or (preferably) autodetect when pdb is involved and in this case not trap exceptions so that they might be intercepted by pdb.

[jaraco]

In 3560f77, I've drafted a change that implements the auto detection concept.

I then applied this diff:

$ git diff
diff --git a/src/pip/_internal/commands/install.py b/src/pip/_internal/commands/install.py
index a9a447872..6b161305e 100644
--- a/src/pip/_internal/commands/install.py
+++ b/src/pip/_internal/commands/install.py
@@ -225,6 +225,7 @@ class InstallCommand(RequirementCommand):
 
     @with_cleanup
     def run(self, options, args):
+        raise RuntimeError('trap me please')
         # type: (Values, List[str]) -> int
         if options.use_user_site and options.target_dir is not None:
             raise CommandError("Can not combine '--user' and '--target'")

to simulate an unhandled exception in the install command.

To demonstrate the effectiveness of the change, here's the old, default behavior:

pip feature/9349-nicer-debug $ .tox/python/bin/python -m pip install foo
ERROR: Exception:
Traceback (most recent call last):
  File "/Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/_internal/cli/base_command.py", line 196, in _trap_run
    status = self.run(options, args)
  File "/Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/_internal/cli/req_command.py", line 178, in wrapper
    return func(self, options, args)
  File "/Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/_internal/commands/install.py", line 228, in run
    raise RuntimeError('trap me please')
RuntimeError: trap me please

And here's what happens when running under pdb:

pip feature/9349-nicer-debug $ .tox/python/bin/python -m pdb -m pip install foo
> /Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/__main__.py(1)<module>()
-> import os
(Pdb) continue
Uncaught exception. Entering post mortem debugging
Running 'cont' or 'step' will restart the program
> /Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/_internal/commands/install.py(228)run()
-> raise RuntimeError('trap me please')
Traceback (most recent call last):
  File "/Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/pdb.py", line 1702, in main
    pdb._runmodule(mainpyfile)
  File "/Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/pdb.py", line 1547, in _runmodule
    self.run(code)
  File "/Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/bdb.py", line 580, in run
    exec(cmd, globals, locals)
  File "/Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/__main__.py", line 1, in <module>
    import os
  File "/Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/_internal/cli/main.py", line 73, in main
    return command.main(cmd_args)
  File "/Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/_internal/cli/base_command.py", line 112, in main
    return self._main(args)
  File "/Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/_internal/cli/base_command.py", line 190, in _main
    status = runner(options, args)
  File "/Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/_internal/cli/req_command.py", line 178, in wrapper
    return func(self, options, args)
  File "/Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/_internal/commands/install.py", line 228, in run
    raise RuntimeError('trap me please')
RuntimeError: trap me please
(Pdb) where
  /Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/pdb.py(1702)main()
-> pdb._runmodule(mainpyfile)
  /Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/pdb.py(1547)_runmodule()
-> self.run(code)
  /Library/Frameworks/Python.framework/Versions/3.9/lib/python3.9/bdb.py(580)run()
-> exec(cmd, globals, locals)
  /Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/__main__.py(1)<module>()
-> import os
  /Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/_internal/cli/main.py(73)main()
-> return command.main(cmd_args)
  /Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/_internal/cli/base_command.py(112)main()
-> return self._main(args)
  /Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/_internal/cli/base_command.py(190)_main()
-> status = runner(options, args)
  /Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/_internal/cli/req_command.py(178)wrapper()
-> return func(self, options, args)
> /Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/_internal/commands/install.py(228)run()
-> raise RuntimeError('trap me please')
(Pdb) quit
Post mortem debugger finished. The pip will be restarted
> /Users/jaraco/code/public/pypa/pip/.tox/python/lib/python3.9/site-packages/pip/__main__.py(1)<module>()
-> import os
(Pdb) 

[MrMino]

Proposition given by @uranusjr that seems safer:

I think our most reasonable approach is providing either an explicit debug entry point, or a flag (e.g. --debug) that disables exception trapping.

IMO python -m pdb -m pip --debug is the one with the least magic involved.