Repository navigation
Move or remove useless/irrelevant command line interface (CLI) on stdlib modules #110076
Description
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
~/.netrcif 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".
Activity
merwok commentedon Sep 29, 2023
Previous comments on this situation:
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 commentedon Sep 29, 2023
Please comment gh-109435. This issue is about modules which have a CLI and not documented on purpose.
AA-Turner commentedon Sep 29, 2023
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 commentedon Sep 29, 2023
Summarising the discussion on Discord:
[me]
[Victor]
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.AA-Turner commentedon Sep 29, 2023
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 commentedon Oct 15, 2023
FYI, there are PRs that aim to make
symtableCLI more useful: #109112 #20757vstinner commentedon Dec 20, 2023
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