pdb CLI argument parsing errors with arguments to module targets

[vivster7]

Bug report

Bug description:

The pdb CLI is no longer correctly forwarding arguments to other tools.

Example reproduction:

• It raises an error pdb: error: argument pyfile: not allowed with argument -m

vscode ➜ ~ $ docker run -it --rm python:3.13.0a2 python -m pdb -m calendar 1
usage: pdb [-h] [-c command] (-m module | pyfile) [args ...]
pdb: error: argument pyfile: not allowed with argument -m

Expected behavior:

• It starts the pdb debugger.

vscode ➜ ~ $ docker run -it --rm python:3.12 python -m pdb -m calendar 1
> /usr/local/lib/python3.12/calendar.py(1)<module>()
-> """Calendar printing functions
(Pdb) 

CPython versions tested on:

3.13

Operating systems tested on:

Linux

Linked PRs

• gh-113548: Allow CLI arguments to pdb -m #113557

[vivster7]

#109165 introduced this regression.

I think the core of the issue is we are trying to parse arguments that we just need to be forwarding. I think treating the -m argument like a boolean argument to indicate "module-mode" and using parse_known_args would be closest to mimicking the behavior of the previous getopt behavior.

[vivster7]

The getopt() function stops processing options as soon as a non-option argument is encountered.

https://docs.python.org/3/library/getopt.html#module-getopt

This is the hardest behavior to reproduce in argparse. Even parse_known_args will break a tool that takes a -c option, because it'll be parsed as an argument to pdb instead. I think this might be an acceptable breaking change though to get rid of getopt.

python -m pdb -m calendar -c foo would be an example command that used to pass the -c foo option to calendar. If we implement parse_known_args, then I think the way to make this work in the future would be python -m pdb -m calendar -- -c foo.

We would only need to pass the -- when the subsequent tool uses -c or --command since those are possible options to pdb.

[gaogaotiantian]

This is actually a symptom for the real serious issue - pdb can't deal with arguments to modules (-m) now.

# This will fail
./python -m pdb -m calendar 1

The problem is, with the current argument parsing method, 1 will be considered as the file to debug and it will conflict with -m. Making -m the boolean introduces other issues:

1. The help message would be confusing
2. Commands like ./python -m pdb calendar -m will execute successfully, which is confusing.

As for the -c part, that's not an issue, because when you have ambiguous options, you have to use -- to separate them clearly, that's true for any CLI and is not a pdb specific issue.

But yes, we need to figure out a way to deal with the arguments to -m and it just seems like we can't have a perfect solution with argparse. We need some tradeoff here.

[gaogaotiantian]

Fixed in #113557