Move or remove useless/irrelevant command line interface (CLI) on stdlib modules

[vstinner]

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.

• ctypes.util: self-test
• curses.has_key: self-test?
• getopt: self-test
• heapq: self-test
• imaplib: self-test, "test the IMAP4_stream class"
• modulefinder: self-test
• symtable: self-test. parse itself (symtable.py)
• textwrap: self-test
• tkinter: self-test
• wsgiref.simple_server: self-test, run a server, open itself in a browser, stop the server.
• xml.sax.xmlreader: self-test.

Maybe demos should be moved as examples in the documentation instead?

• ctypes.textpad: demo
• shlex: print tokens. Is it really useful?
• dbm.__init__: get the DB type... but this CLI is not easy discoverable, it's in the init module!
• netrc: just parse ~/.netrc if available, and then display nothing... not very useful
• smtplib: "Test the sendmail method", try to send an email to localhost SMTP server.
• xmlrpc.client + xmlrpc.server: simple demo.

The random module includes a benchmark. I don't think that it's useful to regular users, it should be moved somewhere else:

• random: benchmark

I'm fine with keeping easter eggs:

• turtle: it's a demo. Looks more like an easter egg or advanced example than "an useful CLI".
• xml.sax.expatreader: Sheakspear easter egg.

See also issue gh-93096 "Decide the fate of undocumented script behavior of some modules".

[merwok]

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.

[vstinner]

I still don’t see the use of a long list, or long table, of all the runnable modules.

Please comment gh-109435. This issue is about modules which have a CLI and not documented on purpose.

[AA-Turner]

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

[AA-Turner]

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 zipapp is 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 / -m modes are poorly / undocumented within the modules.

[AA-Turner]

I agree with this issue though that self-tests should be moved to tests, and demos could be moved to recipies or How-Tos.

[chgnrdv]

FYI, there are PRs that aim to make symtable CLI more useful: #109112 #20757

[vstinner]

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