Thanks for your extended review Steven.

> You state that these two phrases are from the runpy documentation:
>
> * "run from the module namespace"
> * "run from the file system"
>
> but neither of those phrases appear in the runpy documentation here:
>
> https://docs.python.org/3/library/runpy.html

I agree. Actually the first paragraph of the page uses the phrases:

- "located using the module namespace";
- "located using the file system",

so instead of saying:

- "run a module located using the module namespace" to mean "python <file>
- "run a module located using the file system" to mean "python -m <module>",

I simplified to:

- "run from the module namespace"
- "run from the file system"

But since the terminology is misleading I have used these phrases instead:

- `python`: "module initialized from an interactive prompt";
- `python < <file>`: "module initialized from standard input";
- `python <file>`: "module initialized from a file argument";
- `python -c <code>`: "module initialized from a `-c` argument";
- `python -m <module>`: "module initialized from a `-m` argument";
- `import <module>`: "module initialized from an import statement".

What the documentation tries to explain is that in all of these cases except the last one, code is executed in the __main__ module.

I have updated the PR.

----

> The PR changes the term "scope" to "environment", but I think that is wrong. An environment is potentially greater than a scope. `__main__` is a module namespace, hence a scope. The environment includes things outside of that scope, such as the builtins, environment variables, the current working directory, the python path, etc. We don't talk about modules being an environment, but as making up a scope.

I disagree. According to Wikipedia (https://en.wikipedia.org/wiki/Scope_(computer_science)), the term "scope" is the part of a program where a name binding is valid, while the term "environment" (synonym of "context") is the set of name bindings that are valid within a part of a program. Therefore "scope" is a property of a name binding (a name binding has a scope), and "environment" is a property of a part of a program (a part of a program has an environment).

And the term "environment" is actually already used in the original title and synopsis of the document (and it is correct):

> :mod:`__main__` --- Top-level script environment

> .. module:: __main__
>     :synopsis: The environment where the top-level script is run.

So my change to the body fixes the inconsistent and incorrect usage of "scope":

- ``'__main__'`` is the name of the scope in which top-level code executes.
+ ``'__main__'`` is the name of the environment where top-level code is run.

- A module can discover whether or not it is running in the main scope
+ A module can discover whether or not it is running in the main environment

----

> Placing the comment above the `if`, where it will apply to the entire `if` statement, is incorrect.

I agree. Sometimes you see comments before if statements but they usually don't start with "execute".

I have updated the PR.

----

> The second problem is that when running a module with -m it *is* imported. PEP 338 is clear about this:

I agree. I should have said "when the module is not initialized from an import statement".

But note that even before my change the original document already used the phrase "not imported":

- executing code in a module when it is run as a script or with ``python
- -m`` but not when it is imported::
+ executing code in a module when it is not imported::

- # execute only if run as a script
+ # Execute only if the module is not imported.

I have updated the PR.