Issue #25791: Warn when __package__ != __spec__.parent.

In a previous change, __spec__.parent was prioritized over
__package__. That is a backwards-compatibility break, but we do
eventually want __spec__ to be the ground truth for module details. So
this change reverts the change in semantics and instead raises an
ImportWarning when __package__ != __spec__.parent to give people time
to adjust to using spec objects.

1 files changed, 14 insertions, 4 deletions

diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst
index a162851..56049ce 100644
--- a/Doc/reference/import.rst
+++ b/Doc/reference/import.rst
@@ -554,20 +554,30 @@ the module.
    details.
 
    This attribute is used instead of ``__name__`` to calculate explicit
-   relative imports for main modules -- as defined in :pep:`366` --
-   when ``__spec__`` is not defined.
+   relative imports for main modules, as defined in :pep:`366`. It is
+   expected to have the same value as ``__spec__.parent``.
+
+   .. versionchanged:: 3.6
+      The value of ``__package__`` is expected to be the same as
+      ``__spec__.parent``.
 
 .. attribute:: __spec__
 
    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.  Setting ``__spec__``
+   used when importing the module. 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>`.
 
+   When ``__package__`` is not defined, ``__spec__.parent`` is used as
+   a fallback.
+
    .. versionadded:: 3.4
 
+   .. versionchanged:: 3.6
+      ``__spec__.parent`` is used as a fallback when ``__package__`` is
+      not defined.
+
 .. attribute:: __path__
 
    If the module is a package (either regular or namespace), the module