Document all "python -m" utilities

[tebeka]

BPO	28972
Nosy	@gvanrossum, @rhettinger, @tebeka, @aaronchall, @elafontaine, @GadgetSteve

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2016-12-14.13:00:03.262>
labels = ['type-feature', 'docs']
title = 'Document all "python -m" utilities'
updated_at = <Date 2017-09-09.22:26:23.101>
user = 'https://github.com/tebeka'

bugs.python.org fields:

activity = <Date 2017-09-09.22:26:23.101>
actor = 'Aaron Hall'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2016-12-14.13:00:03.262>
creator = 'tebeka'
dependencies = []
files = []
hgrepos = []
issue_num = 28972
keywords = []
message_count = 9.0
messages = ['283190', '283359', '283461', '283470', '283498', '283537', '286839', '300154', '301793']
nosy_count = 7.0
nosy_names = ['gvanrossum', 'rhettinger', 'tebeka', 'docs@python', 'Aaron Hall', 'Eric Lafontaine', 'Steve Barnes']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue28972'
versions = []

[tebeka]

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 http://pythonwise.blogspot.nl/2015/01/python-m.html

[elafontaine]

Hi,

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/script.py".

I believe it's clear though ;
https://docs.python.org/3/using/cmdline.html#cmdoption-m

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.

Regards,
Eric Lafontaine

[rhettinger]

+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: http://bugs.python.org/issue26488

[tebeka]

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 ...

[gvanrossum]

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?

[tebeka]

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 __main__.py or main function.

[elafontaine]

Hi,

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 __main__.py file for the comments, generating the 'index' of all those options from the comments inside the file (main.py). 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 __main__.py 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 __main__.py 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).
Regards,
Eric Lafontaine

[GadgetSteve]

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 __main__.py 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!

[aaronchall]

I like this idea too, but perhaps it should just be a multi-column bulleted list (under the -m flag at https://docs.python.org/3/using/cmdline.html#interface-options) 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.