Description

vstinner

opened on Sep 29, 2023

Issue body actions

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".

Reacted by Erlend E. Aasland, sobolevn and Oleg Iarygin

Activity

1. merwok commented on Sep 29, 2023

   

   merwok

   on Sep 29, 2023

   Member

   More actions

   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.
2. vstinner commented on Sep 29, 2023

   

   vstinner

   on Sep 29, 2023

   MemberAuthor

   More actions

   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.

   Reacted by Éric
3. AA-Turner commented on Sep 29, 2023

   

   AA-Turner

   on Sep 29, 2023

   Member

   More actions

   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
4. AA-Turner commented on Sep 29, 2023

   

   AA-Turner

   on Sep 29, 2023

   Member

   More actions

   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.
5. AA-Turner commented on Sep 29, 2023

   

   AA-Turner

   on Sep 29, 2023

   Member

   More actions

   I agree with this issue though that self-tests should be moved to tests, and demos could be moved to recipies or How-Tos.
6. chgnrdv commented on Oct 15, 2023

   

   chgnrdv

   on Oct 15, 2023

   Contributor

   More actions

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

   added

   stdlibStandard Library Python modules in the Lib/ directoryStandard Library Python modules in the Lib/ directory

   on Nov 28, 2023
8. vstinner commented on Dec 20, 2023

   

   vstinner

   on Dec 20, 2023

   MemberAuthor

   More actions

   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
9. vstinner

   closed this as completedon Dec 20, 2023

Issue actions