Repository navigation
Move or remove useless/irrelevant command line interface (CLI) on stdlib modules #110076
Description
Activity
Previous comments on this situation:
- Document all "python -m" utilities #73158 (comment)
- smtpd-as-a-script feature should be documented and should use argparse #55469 (comment)
- gh-59150: Add table of runnable modules #93410 (comment)
I still don’t see the use of a long list, or long table, of all the runnable modules. They don’t all have the same usefulness and audience, or the same maintained/documented status.
Various other comments were linked at #109435 (comment), too, and my most recent at #109436 (comment), but I don't have time to propose any other changes (or removing the list, which remains my preference to be honest), sorry.
A
Summarising the discussion on Discord:
[me]
I have a slight hesitation on the purpose of such a list. If it’s an idle curiosity thing, lists such as Simon’s & others exist. To be aimed at programmers reading it, I think we ought be clear on the purpose and type of each command-line tool. For example
-m zipappis very different to eg the expat Easter Egg.Éric’s summary of groups I think is useful, but I’m I suppose not yet convinced as to why we need to enumerate all of the modules with script-like behaviour in one place.
[Victor]
I don't think that the sax parser should be documented 🤫
There was also brief discussion on mechanisms to auto-generate such a list, and it was noted that the documentation of many of the CLIs /
-mmodes are poorly / undocumented within the modules.I agree with this issue though that self-tests should be moved to tests, and demos could be moved to recipies or How-Tos.
I failed to find time to look into this issue. I suppose that the status quo can survive a few more months. I close the issue for now
In issue gh-109435, I documented stdlib modules provinding an useful or interesting CLI: https://docs.python.org/dev/library/cmdline.html
Some stdlib modules include self-tests in their main() function. I dislike that and I would suggest to remove it and at least move it to their test suite.
Maybe demos should be moved as examples in the documentation instead?
dbm.__init__: get the DB type... but this CLI is not easy discoverable, it's in the init module!~/.netrcif available, and then display nothing... not very usefulThe random module includes a benchmark. I don't think that it's useful to regular users, it should be moved somewhere else:
I'm fine with keeping easter eggs:
See also issue gh-93096 "Decide the fate of undocumented script behavior of some modules".