Mention of "-m" Flag Missing From Doc on Execution Model

[ericsnowcurrently]

BPO	13474
Nosy	@ncoghlan, @ezio-melotti, @merwok, @ericsnowcurrently, @csabella
PRs	bpo-13474 - add reference to -m usage in execution model #6900 bpo-13474 Add -m reference in context of code execution #6901 bpo-13474: Add -m reference in context of code execution #16045

^{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 = 'https://github.com/ncoghlan'
closed_at = <Date 2019-09-12.13:44:34.984>
created_at = <Date 2011-11-24.20:10:58.388>
labels = ['3.8', 'type-feature', '3.7', 'docs']
title = 'Mention of "-m" Flag Missing From Doc on Execution Model'
updated_at = <Date 2019-09-12.13:44:34.983>
user = 'https://github.com/ericsnowcurrently'

bugs.python.org fields:

activity = <Date 2019-09-12.13:44:34.983>
actor = 'mdk'
assignee = 'ncoghlan'
closed = True
closed_date = <Date 2019-09-12.13:44:34.984>
closer = 'mdk'
components = ['Documentation']
creation = <Date 2011-11-24.20:10:58.388>
creator = 'eric.snow'
dependencies = []
files = []
hgrepos = []
issue_num = 13474
keywords = ['patch']
message_count = 3.0
messages = ['148288', '148398', '316914']
nosy_count = 6.0
nosy_names = ['ncoghlan', 'ezio.melotti', 'eric.araujo', 'docs@python', 'eric.snow', 'cheryl.sabella']
pr_nums = ['6900', '6901', '16045']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue13474'
versions = ['Python 2.7', 'Python 3.7', 'Python 3.8']

[ericsnowcurrently]

The doc on code execution[1] leaves out mention of the -m flag. Seems like it belongs there too.

[1] Doc/reference/executionmodel.rst

[merwok]

I guess you’re suggesting adding a mention of -m in the section near the top that says that a script file and code passed to -c are blocks? Makes sense. The same commit could also improve the markup to link to the description of script, -c and -m in using/cmdline. (I think we have another doc bug open about cross-linking using/cmdline and other parts, but I don’t have the number at hand.)

[ncoghlan]

I've assigned the PR and issue to myself, as the proposed addition in the PR isn't quite right, but it isn't immediately obvious why not.

The gist of the problem is that the current docs are actually correct and complete: modules are the first thing listed as being code blocks, and whether you import them or execute them as __main__ doesn't change that.

However, I can also see why 2011-Eric thought it looked incomplete, so I'm thinking it may make sense to restructure that entire paragraph as a bulleted list, where it would be possible to mention both imported modules and modules executed as main, without giving the impression that those are inherently different things.