[Python-checkins] cpython: Issue #19697: Document cases where __main__.__spec__ is None.

[eric.snow]

http://hg.python.org/cpython/rev/21d8222b667f
changeset:   90015:21d8222b667f
user:        Eric Snow <ericsnowcurrently at gmail.com>
date:        Fri Mar 28 18:10:33 2014 -0600
summary:
  Issue #19697: Document cases where __main__.__spec__ is None.

files:
  Doc/reference/import.rst |  42 +++++++++++++++++++++++++++-
  Misc/NEWS                |   2 +
  2 files changed, 43 insertions(+), 1 deletions(-)


diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst
--- a/Doc/reference/import.rst
+++ b/Doc/reference/import.rst
@@ -519,7 +519,10 @@
 
    The ``__spec__`` attribute must be set to the module spec that was
    used when importing the module.  This is used primarily for
-   introspection and during reloading.
+   introspection and during reloading.  Setting ``__spec__``
+   appropriately applies equally to :ref:`modules initialized during
+   interpreter startup <programs>`.  The one exception is ``__main__``,
+   where ``__spec__`` is :ref:`set to None in some cases <main_spec>`.
 
    .. versionadded:: 3.4
 
@@ -829,6 +832,37 @@
 while raising an exception terminates it immediately.
 
 
+Special considerations for __main__
+===================================
+
+The :mod:`__main__` module is a special case relative to Python's import
+system.  As noted :ref:`elsewhere <programs>`, the ``__main__`` module
+is directly initialized at interpreter startup, much like :mod:`sys` and
+:mod:`builtins`.  However, unlike those two, it doesn't strictly
+qualify as a built-in module.  This is because the manner in which
+``__main__`` is initialized depends on the flags and other options with
+which the interpreter is invoked.
+
+.. _main_spec:
+
+__main__.__spec__
+-----------------
+
+Depending on how :mod:`__main__` is initialized, ``__main__.__spec__``
+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.
+
+In :ref:`the remaining cases <using-on-interface-options>`
+``__main__.__spec__`` is set to ``None``:
+
+- interactive prompt
+- -c switch
+- running from stdin
+- running directly from a source or bytecode file
+
+
 Open issues
 ===========
 
@@ -841,6 +875,12 @@
 XXX runpy, pkgutil, et al in the library manual should all get "See Also"
 links at the top pointing to the new import system section.
 
+XXX Add more explanation regarding the different ways in which
+``__main__`` is initialized?
+
+XXX Add more info on ``__main__`` quirks/pitfalls (i.e. copy from
+:pep:`395`).
+
 
 References
 ==========
diff --git a/Misc/NEWS b/Misc/NEWS
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -145,6 +145,8 @@
   required reference material for tool developers that isn't recorded
   anywhere else.
 
+- Issue #19697: Document cases where __main__.__spec__ is None.
+
 Tests
 -----
 

-- 
Repository URL: http://hg.python.org/cpython