René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"Decide the fate of undocumented script behavior of some modules","articleBody":"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:\n\n- kind of smoke tests:\n  - [x] codecs: ~~performs *stdin:latin1 → utf-8 → latin1 → stdout* passthrough~~ edit: it just wraps stdin and stdout then just exits the script (gh-94233)\n  - [ ] curses.has_key: \"Compare the output of this implementation and the ncurses has_key, on platforms where has_key is already available\"\n  - [x] pprint: measures performance (gh-94613 → https://github.com/python/pyperformance/pull/222)\n  - [ ] random: evaluates output statistics of supported generators\n\n- full-fledged crossplatform utils for admin-like users and small automation:\n  - [ ] asyncio: like `python` but allows to use `await` in top-level script code\n  - [ ] cProfile, profile: runs a script under the profiler\n  - [ ] encodings.rot_13: a stream converter\n  - [ ] filecmp: a crossplatform file comparison utility\n  - [ ] fileinput: prints specified files one by another annotating lines with their source\n  - [ ] http.server: makes a directory available as a site; useful to quickly test a static site with relative links\n  - [x] mimetypes: useful for batch processing of files (maybe) (gh-93097)\n  - [ ] modulefinder: the objdump but for Python source files\n  - [ ] netrc: prints content of `.netrc` for a current user\n  - [ ] pdb\n  - [ ] platform: returns a single line like `Windows-10-10.0.19044-SP0`; can be useful in automation\n  - [ ] quopri: a stream converter\n  - [ ] tabnanny\n  - [ ] wsgiref.simple_server - the same as http.server but for APIs; pases a single request and exits\n\n- both:\n  - base64:\n    - [ ] a stream converter\n    - [x] `base64 -t` encodes/decodes `Aladdin:open sesame` and tests if the result is the same as the original (gh-94230)\n\n- demos with no real world application:\n  - [ ] curses.textpad: shows an input area; when a user closes it, prints the text back\n  - [ ] ftplib: a simple one-pass FTP downloader (uses ~/.netrc for login)\n  - [ ] ~getopt: just passes arguments to `getopt()`~ The module is no longer maintained after gh-105735\n  - [ ] imaplib: sending emails to a dead end has no sence but can be used to check if a email client works or got broken\n  - [ ] shlex: parses stdin using `shlex()` and prints the list into stdout\n  - [ ] smtplib: a simple e-mail client\n  - [ ] xmlrpc.server: serves a datetime service\n\n- complex matter; better leave untouched:\n  - idlelib.\\*\n  - tkinter.\\*\n  - turtledemo.\\*\n  - pstats\n\n*Eggs and to-be-removed modules aren't listed.*\n\nWe need to decide what to do with all these undocumented categories.\n\nI propose the following:\n\n- move smoke tests into `test` module with deduplication\n- 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\n- move demos into the docs of the corresponding module\n\n\u003c!-- gh-linked-prs --\u003e\n### Linked PRs\n* gh-131039\n* gh-131068\n* gh-131069\n* gh-131080\n* gh-131081\n* gh-131097\n* gh-131099\n* gh-131130\n* gh-131133\n* gh-131136\n* gh-131137\n* gh-131144\n* gh-131273\n* gh-131408\n* gh-132266\n\u003c!-- /gh-linked-prs --\u003e\n","author":{"url":"https://github.com/arhadthedev","@type":"Person","name":"arhadthedev"},"datePublished":"2022-05-23T08:50:45.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":9},"url":"https://github.com/93096/cpython/issues/93096"}