After writing a blog post about Python’s many CLI tools recently, I wondered why the json module cannot be run as a script (python -m json.tool works but python -m json does not).
I did some digging and found that this decision was made because at the time the json package was added, there was no way to run a package as a script (only modules could be run as scripts until Python 2.7).
I propose either:
Allowing python -m json and python -m json.tool to both work and update the documentation to note the use of python -m jsononly
Allowing both to work, but triggering a DeprecationWarning when python -m json.tool is used
I made a branch to see what these changes might look like. That branch includes the DeprecationWarning approach in particular.
I can see a downside to the deprecation approach, if users may be piping both stderr and stdout to a process/file or if users might accidentally copy-paste the deprecation warning text. I can’t think of any downside to making both approaches work (outside of the usual “now there are 2 ways to do it”).
As @trey notes, deprecation warnings in CLI tools, especially ones where you’re likely to be capturing the output for consumption elsewhere get painful fast. Keeping error output on stderr definitely helps, but not as much as simply not emitting the warning in the first place (e.g. I had to give up on emitting the locale coercion warnings because too many CI processes treated “text was emitted on stderr” as a failure condition).
Given we’d be keeping json.tool around anyway to hold the CLI implementation, there’s no real downside to keeping the if __name__ == "__main__" clause at the end and just having a “version changed” notice in the docs that says “CLI invocation changed to python -m json. Compatibility support for python -m json.tool will be retained indefinitely.”