Decide the fate of undocumented script behavior of some modules

[arhadthedev]

There are three dozens of standard modules that can be called via python -m and their documentation doesn't mention it. They can be grouped into five categories:

• kind of smoke tests:

  • codecs: performs stdin:latin1 → utf-8 → latin1 → stdout passthrough edit: it just wraps stdin and stdout then just exits the script (gh-94233)
  • curses.has_key: "Compare the output of this implementation and the ncurses has_key, on platforms where has_key is already available"
  • pprint: measures performance
  • random: evaluates output statistics of supported generators

• full-fledged crossplatform utils for admin-like users and small automation:

  • asyncio: like python but allows to use await in top-level script code
  • cProfile, profile: runs a script under the profiler
  • encodings.rot_13: a stream converter
  • filecmp: a crossplatform file comparison utility
  • fileinput: prints specified files one by another annotating lines with their source
  • http.server: makes a directory available as a site; useful to quickly test a static site with relative links
  • mimetypes: useful for batch processing of files (maybe)
  • modulefinder: the objdump but for Python source files
  • netrc: prints content of .netrc for a current user
  • pdb
  • platform: returns a single line like Windows-10-10.0.19044-SP0; can be useful in automation
  • quopri: a stream converter
  • tabnanny
  • wsgiref.simple_server - the same as http.server but for APIs; pases a single request and exits

• both:

  • base64:
    • a stream converter
    • base64 -t encodes/decodes Aladdin:open sesame and tests if the result is the same as the original (gh-94230)

• demos with no real world application:

  • curses.textpad: shows an input area; when a user closes it, prints the text back
  • ftplib: a simple one-pass FTP downloader (uses ~/.netrc for login)
  • getopt: just passes arguments to getopt()
  • imaplib: sending emails to a dead end has no sence but can be used to check if a email client works or got broken
  • shlex: parses stdin using shlex() and prints the list into stdout
  • smtplib: a simple e-mail client
  • xmlrpc.server: serves a datetime service

• complex matter; better leave untouched:

  • idlelib.*
  • tkinter.*
  • turtledemo.*
  • pstats

Eggs and to-be-removed modules aren't listed.

We need to decide what to do with all these undocumented categories.

I propose the following:

• move smoke tests into test module with deduplication
• for full-fledged utils, add Command-Line Usage into the docs like in https://docs.python.org/3/library/ast.html#command-line-usage or https://docs.python.org/3/library/trace.html#command-line-usage
• move demos into the docs of the corresponding module

[ericvsmith]

pprint also has a rudimentary performance test. See #92546 for a bug, where it wasn't being tested. If we really care about this performance metric, it should be moved to a proper benchmark.

[arhadthedev]

@ericvsmith Thank you, I've added it to the list.