bpo-30840: Document relative imports (#12831)
* document relative imports
* 📜🤖 Added by blurb_it.
* fix indentation error
* remove indentation
* Document relative imports
* Document relative imports
* remove from ...package
* Document relative imports
* remove trailing space
* Document relative imports
* Document relative imports
diff --git a/Doc/reference/import.rst b/Doc/reference/import.rst
index 9a0ab39..88290c8 100644
--- a/Doc/reference/import.rst
+++ b/Doc/reference/import.rst
@@ -921,6 +921,46 @@
``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__
===================================