[Python-checkins] r47272 - python/trunk/Doc/tut/tut.tex

[nick.coghlan]

Author: nick.coghlan
Date: Thu Jul  6 15:04:56 2006
New Revision: 47272

Modified:
   python/trunk/Doc/tut/tut.tex
Log:
Update the tutorial section on relative imports

Modified: python/trunk/Doc/tut/tut.tex
==============================================================================
--- python/trunk/Doc/tut/tut.tex	(original)
+++ python/trunk/Doc/tut/tut.tex	Thu Jul  6 15:04:56 2006
@@ -2919,14 +2919,13 @@
 
 The submodules often need to refer to each other.  For example, the
 \module{surround} module might use the \module{echo} module.  In fact,
-such references
-are so common that the \keyword{import} statement first looks in the
-containing package before looking in the standard module search path.
-Thus, the surround module can simply use \code{import echo} or
-\code{from echo import echofilter}.  If the imported module is not
-found in the current package (the package of which the current module
-is a submodule), the \keyword{import} statement looks for a top-level
-module with the given name.
+such references are so common that the \keyword{import} statement
+first looks in the containing package before looking in the standard
+module search path. Thus, the \module{surround} module can simply use
+\code{import echo} or \code{from echo import echofilter}.  If the
+imported module is not found in the current package (the package of
+which the current module is a submodule), the \keyword{import}
+statement looks for a top-level module with the given name.
 
 When packages are structured into subpackages (as with the
 \module{Sound} package in the example), there's no shortcut to refer
@@ -2936,6 +2935,24 @@
 in the \module{Sound.Effects} package, it can use \code{from
 Sound.Effects import echo}.
 
+Starting with Python 2.5, in addition to the implicit relative imports
+described above, you can write explicit relative imports with the
+\code{from module import name} form of import statement. These explicit
+relative imports use leading dots to indicate the current and parent
+packages involved in the relative import. From the \module{surround}
+module for example, you might use:
+
+\begin{verbatim}
+from . import echo
+from .. import Formats
+from ..Filters import equalizer
+\end{verbatim}
+
+Note that both explicit and implicit relative imports are based on the
+name of the current module. Since the name of the main module is always
+\code{"__main__"}, modules intended for use as the main module of a
+Python application should always use absolute imports.
+
 \subsection{Packages in Multiple Directories}
 
 Packages support one more special attribute, \member{__path__}.  This