]> granicus.if.org Git - python/commitdiff
Issue #19697: Document cases where __main__.__spec__ is None.
authorEric Snow <ericsnowcurrently@gmail.com>
Sat, 29 Mar 2014 00:10:33 +0000 (18:10 -0600)
committerEric Snow <ericsnowcurrently@gmail.com>
Sat, 29 Mar 2014 00:10:33 +0000 (18:10 -0600)
Doc/reference/import.rst
Misc/NEWS

index 1b28d2c67a6c5ace5c5a3dd01d7cbd6fcc68cdc5..e35276fd4ba5323a6b4e8902dc24c4d2e2a48df4 100644 (file)
@@ -519,7 +519,10 @@ the module.
 
    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 @@ it is sufficient to raise :exc:`ImportError` directly from
 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 @@ related entries in the data model reference page?
 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
 ==========
index 6b0fa75b3a393972094bcac8b0a09270c2b5cd07..c68238641cc86b7184dabda37668051bde17d7ff 100644 (file)
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -115,6 +115,8 @@ Documentation
   required reference material for tool developers that isn't recorded
   anywhere else.
 
+- Issue #19697: Document cases where __main__.__spec__ is None.
+
 Tests
 -----