gh-59150: Add table of runnable modules

[slateny]

#59150

https://docs.python.org/dev/using/cmdline.html#cmdoption-m

Looks roughly like

but much longer. For checking that the docs mention -m:

Skipped py_compile as I couldn't find documentation; asyncio's documentation is only on the 3.8 what's new; xmlrpc.client documentation is in xmlrpc.server; pickle documentation is in pickletool

[arhadthedev]

but much longer.

It can be even longer, see gh-93096.

[slateny]

@arhadthedev Thanks for making the list - the ones I have here were just found via something like grep "python+ -m ", so the ones that didn't have documentation were skipped over.

[carlbordum]

I like this :)

[rhettinger]

Guido, the last time this came up, I think you recommended not doing this on the theory that the standard library is primarily a library for people writing software and not a collection of command-line tools, some of which were added as simple demonstrations and were not intended to be stable production tools. And generally the test code is an implementation detail, just a convenience for the module maintainers and not something guaranteed by the docs.

[merwok]

IDLE is primarily an application, and secondly a module for use by IDLE extension writers. So I wouldn’t change this heading!

[merwok]

The modules that are runnable as scripts have various degree of support and also different intended audiences.
Compare zipapp that is meant to be used as a program, http.server that is sort of an easter egg found in lists of tips and tricks, site that’s really more of a debugging helper that most people will never know about until someone debugging an issue asks them to run it. So if these end up documenting, first I am not convinced that the doc for python -m is the right place, and second I would not have one long list but rather meaningful groupings.

[gvanrossum]

As long as we're making updates to this, while I originally wrote it, maybe the more useful information is the current maintainer (Terry Reedy).

[gvanrossum]

I have to agree with @rhettinger that this is not the right place to document this.

[slateny]

Would you say that such a list should be on some other page instead, or that it shouldn't be on the official docs at all?

[gvanrossum]

I feel that it doesn't make sense for such a list to exist. What would you do with such a list? It's like making a list of all UNIX commands that have a -j flag.

[arhadthedev]

It's like making a list of all UNIX commands that have a -j flag.

Who is a target audience of the tools?

Currently the documentation is dedicated to Python programmers and CPython plugin authors. The most of tools, however, seems to be for more broad audience like sysadmin users. Should we force them to sift through a sizable man(3)-like docs while they, expecting just man(1), need nothing more than simple advertisement of available CLI tools to keep them on the belt?

[gvanrossum]

That's as good an argument against inluding this list as any, because half the commands supported here are of no use to sysadmin users (unless they are also Python programmers). If you want to post this list (or something like it) in a blog or on realpython.com, feel free, but the Python docs are for Python programmers.

[merwok]

Closing this PR as we don’t want a long list of all modules, and not in that document.
The issue can stay open a bit to see if people come up with useful sub-lists for some of the modules and better locations for them.

[slateny]

Closing this PR as we don’t want a long list of all modules, and not in that document. The issue can stay open a bit to see if people come up with useful sub-lists for some of the modules and better locations for them.

The comments above said that there shouldn't be a list at all, and if I'm reading it right then sublists, even if grouped well, would seem to follow the same reasoning.

I'm not too sure where the list would better go either if not the section describes the command line option. Maybe parts of the tutorial that touch on these modules can have an extra line that references the cli option, but then the list isn't quite a list anymore.

[gvanrossum]

It doesn't really belong in the tutorial either IMO -- this information should be listed with specific modules, e.g. the pdb section should document the CLI behavior.

[merwok]

From my previous message here or Nick’s message on the ticket, some examples of specific subsets could be:

• -m site and -m sysconfig help debug your local installation and paths/envvars issues; these could be listed in the reference doc for how sys.path is constructed (not a tuto!)

• -m pdb is useful for python developers, like -m timeit and sometimes -m compileall, but others like -m pickle and -m tokenize are less generally useful and more for debugging CPython development itself (but maybe I’m unaware of other uses)

• -m zipapp is its own program, and is already documented in the module docs; not sure there would be any value in also mentioning it in a list on another page

• -m zipfile and -m http.server and others are often found in articles about secret gems in the stdlib, as tools that can be convenient to use when you don’t have regular zip or http server programs installed; but there is no natural place to list all of them, and we also don’t want to make promises about their status, features or quality, so maybe they are fine as little hidden helpers.

Having written this, I now agree with Guido that a specific mention in each module’s specific docs is enough, and should be done on a case by case basis (and not for all of them). Will close the issue too.

[vstinner]

Implemented in issue gh-109435 as new documentation page: https://docs.python.org/dev/library/cmdline.html

If you prefer a table, you can propose a PR to enhance how the list is rendered.