Document the possible values for __main__.__spec__

[brettcannon]

BPO	19697
Nosy	@brettcannon, @ncoghlan, @ericsnowcurrently
Dependencies	bpo-19700: Update runpy for PEP 451
Files	issue19697-basic.diff: basic initial additions

^{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 = <Date 2014-03-29.00:32:06.615>
created_at = <Date 2013-11-22.16:25:46.883>
labels = ['interpreter-core', 'type-feature']
title = 'Document the possible values for __main__.__spec__'
updated_at = <Date 2014-03-29.05:41:34.703>
user = 'https://github.com/brettcannon'

bugs.python.org fields:

activity = <Date 2014-03-29.05:41:34.703>
actor = 'python-dev'
assignee = 'none'
closed = True
closed_date = <Date 2014-03-29.00:32:06.615>
closer = 'eric.snow'
components = ['Interpreter Core']
creation = <Date 2013-11-22.16:25:46.883>
creator = 'brett.cannon'
dependencies = ['19700']
files = ['34656']
hgrepos = []
issue_num = 19697
keywords = ['patch']
message_count = 17.0
messages = ['203796', '203945', '204030', '207267', '207268', '207269', '207271', '207272', '207273', '215078', '215093', '215098', '215099', '215100', '215101', '215102', '215114']
nosy_count = 5.0
nosy_names = ['brett.cannon', 'ncoghlan', 'Arfrever', 'python-dev', 'eric.snow']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue19697'
versions = ['Python 3.4', 'Python 3.5']

[brettcannon]

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

[ericsnowcurrently]

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>

[ncoghlan]

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 :)

[ericsnowcurrently]

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

Thoughts?

See:

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

[ericsnowcurrently]

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

[ericsnowcurrently]

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

[ncoghlan]

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

[ericsnowcurrently]

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?

[ncoghlan]

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

[ericsnowcurrently]

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

[ncoghlan]

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.

[ericsnowcurrently]

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.