Title: Document all "python -m" utilities
Type: enhancement Stage:
Components: Documentation Versions:
Status: open Resolution:
Dependencies: Superseder:
Assigned To: Nosy List: Aaron Hall, Eric Lafontaine, Steve Barnes, docs@python, gvanrossum, rhettinger, tebeka
Priority: normal Keywords:

Created on 2016-12-14 13:00 by tebeka, last changed 2017-09-09 22:26 by Aaron Hall.

Messages (9)
msg283190 - (view) Author: Miki Tebeka (tebeka) * Date: 2016-12-14 13:00
Several modules can be invoked with -m and are pretty handy (json.tool, zipfile, tarfile ...).

There should be a section in the documentation that groups all of these "python -m" tools together. Something like
msg283359 - (view) Author: Eric Lafontaine (Eric Lafontaine) * Date: 2016-12-16 01:22

I believe it's already done.  The only thing that people tends to forget is that doing python -m "module.script(.py)" is only doing the equivalent of "python module/". 

I believe it's clear though ;

Any module that anyone has done can do it, so it would be up to the module developer to put it in the README/Description of the module to describe how to use it.  That's what I think

BTW, I'm just giving my opinion out of contributing.  Please don't see it as a denial as it's not the case.  Python strive to be clearer but has 20 years of existence.  Enhancing it is hard.

Eric Lafontaine
msg283461 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2016-12-17 02:05
+1 for Miki's idea.  It would be nice if there were a single page that collected together all the command-line tools (with examples).  It should include a 2to3 example as well.  Also, there should be some indication of which tools we guarantee to be available (2to3 json.tool) versus those that just happen to be exposed but are subject to change (possibly because they were just used for testing, or because they have a crummy API, or because Guido has said that we are in the library business, not the command-line tool business).

See also:
msg283470 - (view) Author: Miki Tebeka (tebeka) * Date: 2016-12-17 07:52
Eric - sorry I wasn't clear. I'm not talking about the -m behavior in general but on the modules in the standard library that can be used with it. A lot of windows are happy to know about "python -m tarfile" to they can extract tar files without installing an extra tool and some Linux people are happy to know on "python -m zipfile" so they don't have to install the "zip" utility to extract/create zip archives. etc ...
msg283498 - (view) Author: Guido van Rossum (gvanrossum) * (Python committer) Date: 2016-12-17 16:26
I'm neutral on this idea.  I would much rather focus on making sure that the various modules (such as pdb or tarfile) which have useful command-line functionality document that clearly and uniformly, but as part of each module's library docs.

I don't think that a list of all modules that have such behavior really belongs in the stdlib docs, but if someone wants to add it and keep it up to date I won't object.  Just understand that whatever is documented must preserve some sort of backwards compatibility.  And don't repeat the same information in two places.

Maybe the blog post that started this is actually enough?  Or if something more official is needed, perhaps a how-to document?
msg283537 - (view) Author: Miki Tebeka (tebeka) * Date: 2016-12-18 05:17
Thanks Guido, however I think my blog is not the right place - it's dog ugly and read by about 7 people on a good day :) 

I think that adding this to the official docs will add to the "batteries included" motto. I'll try to find a time and come up with a patch to the docs, however if this goes through we should place a note somewhere in the development docs about updating this section as well if someone adds a or main function.
msg286839 - (view) Author: Eric Lafontaine (Eric Lafontaine) * Date: 2017-02-03 02:37

I've just watched the old David Beazley video about the packaging system in python and got me thinking about this issue.

I'm throwing the idea, please critize it!

If we were to make a "hook" for the .rst files of the modules to go and scan the file for the comments, generating the 'index' of all those options from the comments inside the file (  That would be in my opinion a solution to make sure they are kept to date and would also insure someone knows minimally what he's doing as he's playing inside the main of a package.  The idea is similar to the autodoc module of sphinx that scan a module for the doc, but would apply to the only.  However, I've just started with .rst files and I'm not sure how we could 'implement' that and even less if it's possible at all.

(BTW, I would only enable the .rst "hook" option generation on the file as to keep sort of a standardisation but not obligation)

P.S. I know I initially seems skeptical, but I have started to see the use thanks to you :)  The example was good (msg283470).  
Eric Lafontaine
msg300154 - (view) Author: Steve Barnes (Steve Barnes) * Date: 2017-08-11 06:53
Having done some checks for the practicality of auto documenting library items with a -m command line usage I have to say that it will not be so simple. 

Many of the library items that provide useful functionality, including zipfile & tarfile, are implemented as single .py files, rather than as modules so have no to trigger the inclusion in auto-generated documentation. 

I also tried searching for standard library items that use `if __name__ == "__main__":` constructs but, of course, many files simply use that to expose tests rather than useful functionality - so that is out as well. I even thought of trying for a regex that would look for this followed, in the same scope by argparse but of course there is no obligation to use it.

And of course main() does not HAVE to be called main so that is out.

Sorry to scotch the idea Eric!
msg301793 - (view) Author: Aaron Hall (Aaron Hall) * Date: 2017-09-09 22:26
I like this idea too, but perhaps it should just be a multi-column bulleted list (under the -m flag at with links to the respective Standard Library doc?

Then we just ensure the documentation for the module is complete with examples for the command line usage.
Date User Action Args
2017-09-09 22:26:23Aaron Hallsetnosy: + Aaron Hall
messages: + msg301793
2017-08-11 06:53:45Steve Barnessetnosy: + Steve Barnes
messages: + msg300154
2017-02-03 02:37:49Eric Lafontainesetmessages: + msg286839
2016-12-18 05:17:12tebekasetmessages: + msg283537
2016-12-17 16:26:25gvanrossumsetmessages: + msg283498
2016-12-17 07:52:12tebekasetmessages: + msg283470
2016-12-17 02:05:53rhettingersetassignee: docs@python ->

messages: + msg283461
nosy: + gvanrossum, rhettinger
2016-12-16 01:22:14Eric Lafontainesetnosy: + Eric Lafontaine
messages: + msg283359
2016-12-14 13:00:03tebekacreate