So that e.g. __main__.__spec__.name is the actual name of the module being executed.

I've already started on this somewhat.  However, I'm going to close out more of the other PEP 451 issues before going any further.

Nick: when do you think things will settle down that you could field a question or two and some reviews relative to the __main__ changes.  I keep wondering if I'll have inadvertently implemented good chunks of PEP 395 by the time I'm done here. <wink>

Yes, PEP 451 addresses a few of the PEP 395 issues. Between this and PEP
420, I actually plan to withdraw that PEP as out of date.

All my pre-beta commits are done, so ask away :)

Here's an outline of how I see __main__.__spec__ playing out relative to the various cmdline interfaces.

== == == === ==== ======== ======== ======== ======== ============
-  -c -m dir file name     loader   origin   cached   has_location
== == == === ==== ======== ======== ======== ======== ============
                  __main__ builtin  -        None     False
X                 __main__ builtin  -        None     False
   X              __main__ builtin  -c       None     False
      X           (finder) (finder) (finder) (finder) (finder)
         X        __main__ <loader> path     None     True
             X    __main__ <loader> path     None     True
== == == === ==== ======== ======== ======== ======== ============

Note: __main__.__spec__ in the -m case is addressed in issue #19700.

Thoughts?

See:

[1] http://docs.python.org/3.4/using/cmdline.html
[2] Python/pythonrun.c
[3] Modules/main.c

For the record, normal start-up happens like this (simplified):

1. prep for and create/initialize interpreter
2. exec the site module in the __main__ namespace (unless -S)
3. do the interface-specific stuff

Note: exec of the site module does not impact the spec.

In the case where -i/PYTHONINSPECT is issued (or implied):

1. ...
2. ...
3. exec the PYTHONSTARTUP script (if set and it exists)
4. do the interface-specific stuff
5. start the REPL

Note: the -i case does not impact the spec, nor does the exec of any PYTHONSTARTUP script.


See:

[1] http://docs.python.org/3.4/using/cmdline.html
[2] Python/pythonrun.c
[3] Modules/main.c
[4] PEP 432

Food for thought:

We could (for 3.5) add an importer just for __main__ that gives us the appropriate spec and loads __main__ accordingly.  Such a loader could even incorporate exec of the site module (and any PYTHONSTARTUP script).

You'd also need to update the new multiprocessing code - it currently expects "__main__.__spec__ == None" for all the run-from-a-path-or-stdin cases.

The -m switch and running __main__ from a supplied sys.path entry (the "dir" entry in your table) are both already handled by the runpy changes in issue 19700.

The remaining cases where __main__.__spec__ is currently None:

- interactive prompt
- -c switch
- running from stdin
- running directly from a source or bytecode file

To be honest, I'm not sure it actually makes sense to try to manufacture a pseudo-spec for those cases. A main script may not be importable as a module (e.g. a hyphen in its name, or no .py suffix), and you *definitely* can't import a file that doesn't exist on disk (REPL, stdin, -c).

I'm fine with leaving __spec__ as None for those remaining cases.  It definitely simplifies this ticket. :)  Do you see any reason to not close this one at this point?

I think we need to document this somewhere. Not exactly sure where though - a new subsection in the import reference, perhaps?

Here's a basic patch.  It introduces __main__ in import.rst and then identifies the cases where __spec__ is set to None or otherwise.

There are a few :ref: links to labels on other pages that I had trouble with.  I'll address those when I put up a new draft after feedback.  Any suggestions on making them work would be helpful. :)

Looks like a reasonable general structure to me.

For label references, you don't want to include the leading underscore - that's part of the label syntax, not the label itself.

That did the trick, Nick.  I swear there's always something I forget about ReST. :)

Otherwise do you have any objections to the patch?  I imagine there's more we could put in the section (for language spec purposes), but I figure what I have there is good enough for the moment.

"is some cases" is a typo, but otherwise, yeah, may as well commit this so the website gets updated while we decide what else (if anything) we want to cover.

New changeset 21d8222b667f by Eric Snow in branch 'default':
Issue #19697: Document cases where __main__.__spec__ is None.
http://hg.python.org/cpython/rev/21d8222b667f

New changeset 4972475ae2e7 by Eric Snow in branch '3.4':
Issue #19697: Document cases where __main__.__spec__ is None.
http://hg.python.org/cpython/rev/4972475ae2e7

Wish I had done that in the opposite direction.  Anyway, thanks Nick.

New changeset 0427c2ff653d by Nick Coghlan in branch '3.4':
Issue #19697: document more __main__.__spec__ quirks
http://hg.python.org/cpython/rev/0427c2ff653d

New changeset a90254be2da2 by Nick Coghlan in branch 'default':
Issue #19697: merge docs from 3.4
http://hg.python.org/cpython/rev/a90254be2da2