From 4d0233ec656bc7e7814e5f6f484e79a50a0daf91 Mon Sep 17 00:00:00 2001
From: "Miss Islington (bot)"
 <31488909+miss-islington@users.noreply.github.com>
Date: Wed, 24 Apr 2019 08:44:19 -0700
Subject: [PATCH] bpo-30840: Document relative imports (GH-12831) (GH-12938)

* Document relative imports
(cherry picked from commit 70bf713617e15fad390ed953e48b3c65d9bc90ec)

Co-authored-by: Joannah Nanjekye <33177550+nanjekyejoannah@users.noreply.github.com>
---
 Doc/reference/import.rst                      | 40 +++++++++++++++++++
 Doc/reference/simple_stmts.rst                |  3 +-
 .../2019-04-14-19-46-21.bpo-30840.R-JFzw.rst  |  1 +
 3 files changed, 43 insertions(+), 1 deletion(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2019-04-14-19-46-21.bpo-30840.R-JFzw.rst

diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst
index 9a0ab39d3b4a..88290c88bb35 100644
--- a/Doc/reference/import.rst
+++ b/Doc/reference/import.rst
@@ -921,6 +921,46 @@ it is sufficient to raise :exc:`ModuleNotFoundError` directly from
 ``None``. The latter indicates that the meta path search should continue,
 while raising an exception terminates it immediately.
 
+.. _relativeimports:
+
+Package Relative Imports
+========================
+
+Relative imports use leading dots. A single leading dot indicates a relative
+import, starting with the current package. Two or more leading dots indicate a
+relative import to the parent(s) of the current package, one level per dot
+after the first. For example, given the following package layout::
+
+    package/
+        __init__.py
+        subpackage1/
+            __init__.py
+            moduleX.py
+            moduleY.py
+        subpackage2/
+            __init__.py
+            moduleZ.py
+        moduleA.py
+
+In either ``subpackage1/moduleX.py`` or ``subpackage1/__init__.py``,
+the following are valid relative imports::
+
+    from .moduleY import spam
+    from .moduleY import spam as ham
+    from . import moduleY
+    from ..subpackage1 import moduleY
+    from ..subpackage2.moduleZ import eggs
+    from ..moduleA import foo
+
+Absolute imports may use either the ``import <>`` or ``from <> import <>``
+syntax, but relative imports may only use the second form; the reason
+for this is that::
+
+    import XXX.YYY.ZZZ
+
+should expose ``XXX.YYY.ZZZ`` as a usable expression, but .moduleY is
+not a valid expression.
+
 
 Special considerations for __main__
 ===================================
diff --git a/Doc/reference/simple_stmts.rst b/Doc/reference/simple_stmts.rst
index 07072d954384..1779832a9fdd 100644
--- a/Doc/reference/simple_stmts.rst
+++ b/Doc/reference/simple_stmts.rst
@@ -829,7 +829,8 @@ exists. Two dots means up one package level. Three dots is up two levels, etc.
 So if you execute ``from . import mod`` from a module in the ``pkg`` package
 then you will end up importing ``pkg.mod``. If you execute ``from ..subpkg2
 import mod`` from within ``pkg.subpkg1`` you will import ``pkg.subpkg2.mod``.
-The specification for relative imports is contained within :pep:`328`.
+The specification for relative imports is contained in
+the :ref:`relativeimports` section.
 
 :func:`importlib.import_module` is provided to support applications that
 determine dynamically the modules to be loaded.
diff --git a/Misc/NEWS.d/next/Documentation/2019-04-14-19-46-21.bpo-30840.R-JFzw.rst b/Misc/NEWS.d/next/Documentation/2019-04-14-19-46-21.bpo-30840.R-JFzw.rst
new file mode 100644
index 000000000000..210f54f2593e
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2019-04-14-19-46-21.bpo-30840.R-JFzw.rst
@@ -0,0 +1 @@
+Document relative imports
\ No newline at end of file
-- 
2.47.3