Skip to content

Document all "python -m" utilities #73158

Closed as not planned
Closed as not planned
Document all "python -m" utilities#73158
Labels
docsDocumentation in the Doc dirtype-featureA feature request or enhancement

Description

@tebeka
tebeka
mannequin
opened on Dec 14, 2016
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 = []

Activity

  1. tebeka commented on Dec 14, 2016

    @tebeka
    tebekamannequin
    on Dec 14, 2016
    MannequinAuthor

    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

  2. tebeka
    assigned
    docspython
    on Dec 14, 2016
  3. tebeka
    added
    docsDocumentation in the Doc dir
    type-featureA feature request or enhancement
    on Dec 14, 2016

  4. elafontaine commented on Dec 16, 2016

    @elafontaine
    elafontainemannequin
    on Dec 16, 2016
    Mannequin

    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

  5. rhettinger commented on Dec 17, 2016

    @rhettinger
    rhettinger
    on Dec 17, 2016
    Contributor

    +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

  6. rhettinger
    unassigned
    docspython
    on Dec 17, 2016

  7. tebeka commented on Dec 17, 2016

    @tebeka
    tebekamannequin
    on Dec 17, 2016
    MannequinAuthor

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

  8. gvanrossum commented on Dec 17, 2016

    @gvanrossum
    gvanrossum
    on Dec 17, 2016
    Member

    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?

  9. tebeka commented on Dec 18, 2016

    @tebeka
    tebekamannequin
    on Dec 18, 2016
    MannequinAuthor

    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.

  10. elafontaine commented on Feb 3, 2017

    @elafontaine
    elafontainemannequin
    on Feb 3, 2017
    Mannequin

    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

  11. GadgetSteve commented on Aug 11, 2017

    @GadgetSteve
    GadgetStevemannequin
    on Aug 11, 2017
    Mannequin

    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!

  12. aaronchall commented on Sep 9, 2017

    @aaronchall
    aaronchallmannequin
    on Sep 9, 2017
    Mannequin

    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.

  13. ezio-melotti
    transferred this issue fromon Apr 10, 2022
  14. erlend-aasland
    added this to Argparse issueson Jul 30, 2022

  15. slateny commented on Aug 23, 2022

    @slateny
    slateny
    on Aug 23, 2022
    Contributor

    Per comment and discussion in #93410, closing as the ability to be used as -m should be listed in the modules themselves over a complete list.

  16. slateny
    closed this as not plannedon Aug 23, 2022
  17. slateny
    moved this to Doc issues in Argparse issueson Aug 23, 2022

  18. vstinner commented on Sep 29, 2023

    @vstinner
    vstinner
    on Sep 29, 2023
    Member

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

  19. merwok commented on Sep 29, 2023

    @merwok
    merwok
    on Sep 29, 2023
    Member

    So previous discussions were ignored and a long list of dubious utility was added after being previously rejected?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation in the Doc dirtype-featureA feature request or enhancement

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions