Decide the fate of undocumented script behavior of some modules

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 (gh-94613 → https://github.com/python/pyperformance/pull/222)
  • 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) (gh-93097)
  • 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() The module is no longer maintained after gh-105735
  • 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

Linked PRs

• gh-131039
• gh-131068
• gh-131069
• gh-131080
• gh-131081
• gh-131097
• gh-131099
• gh-131130
• gh-131133
• gh-131136
• gh-131137
• gh-131144
• gh-131273
• gh-131408
• gh-132266

Bắt đầu bằng cách xem xét các danh mục module được liệt kê và các phần „Command-Line Usage“ hiện có trong tài liệu ast và trace. Kiểm tra các PR được liên kết để hiểu những mục nào đang được xử lý, sau đó xác định liệu từng hành vi còn lại thuộc về module kiểm thử hay tài liệu của module tương ứng. Công việc được xem là hoàn tất khi đã quyết định hướng xử lý cho mọi danh mục được liệt kê và các thay đổi tài liệu hoặc kiểm thử phát sinh đã được ghi lại.