changeset:   90022:a90254be2da2
parent:      90020:bca58d3cf035
parent:      90021:0427c2ff653d
user:        Nick Coghlan <ncoghlan@gmail.com>
date:        Sat Mar 29 15:41:18 2014 +1000
description:
Issue #19697: merge docs from 3.4


diff -r bca58d3cf035 -r a90254be2da2 Doc/reference/import.rst
--- a/Doc/reference/import.rst	Fri Mar 28 23:36:43 2014 -0500
+++ b/Doc/reference/import.rst	Sat Mar 29 15:41:18 2014 +1000
@@ -852,16 +852,30 @@
 gets set appropriately or to ``None``.
 
 When Python is started with the :option:`-m` option, ``__spec__`` is set
-to the module spec of the corresponding module.
+to the module spec of the corresponding module or package. ``__spec__`` is
+also populated when the ``__main__`` module is loaded as part of executing a
+directory, zipfile or other :data:`sys.path` entry.
 
 In :ref:`the remaining cases <using-on-interface-options>`
-``__main__.__spec__`` is set to ``None``:
+``__main__.__spec__`` is set to ``None``, as the code used to populate the
+:mod:`__main__` does not correspond directly with an importable module:
 
 - interactive prompt
 - -c switch
 - running from stdin
 - running directly from a source or bytecode file
 
+Note that ``__main__.__spec__`` is always ``None`` in the last case,
+*even if* the file could technically be imported directly as a module
+instead. Use the :option:`-m` switch if valid module metadata is desired
+in :mod:`__main__`.
+
+Note also that even when ``__main__`` corresponds with an importable module
+and ``__main__.__spec__`` is set accordingly, they're still considered
+*distinct* modules. This is due to the fact that blocks guarded by
+``if __name__ == "__main__":`` checks only execute when the module is used
+to populate the ``__main__`` namespace, and not during normal import.
+
 
 Open issues
 ===========