Update the guidance on imports to account for what we've learned in the last four years.
diff --git a/PythonStyleGuide.wiki b/PythonStyleGuide.wiki
index c61610d..b33ce75 100644
--- a/PythonStyleGuide.wiki
+++ b/PythonStyleGuide.wiki
@@ -29,8 +29,7 @@
== Python Language Rules ==
# [PythonStyleGuide#pychecker pychecker]: _Recommended_
- # [PythonStyleGuide#Module_and_package_imports Module and package imports]: _Yes, *except for wildcard imports*_
- # [PythonStyleGuide#Packages Packages]: _Yes_
+ # [PythonStyleGuide#Imports Imports]: _Import only modules and only by name *(no wildcard imports)*_
# [PythonStyleGuide#Exceptions Exceptions]: _Yes_
# [PythonStyleGuide#Global_variables Global variables]: _Use sparingly_
# [PythonStyleGuide#Nested_Local_Inner_Classes_and_Functions Nested/Local/Inner Classes and Functions]: _Yes_
@@ -124,23 +123,28 @@
You can find more information on the
[http://www.google.com/url?sa=D&q=http://pychecker.sourceforge.net PyChecker homepage].
-== Module and package imports ==
+== Imports ==
-*What it is:* Reusability mechanism for sharing code from one module to another.
+*What it is:* Mechanism for making use of code between modules.
-*Pros:* Simplest way of sharing things and the most commonly used one, too.
+*Pros:* Very flexible relative to other languages. Packages, modules, classes,
+functions, and fields all may be imported.
-*Cons:* `from foo import *` or `from foo import Bar` is very nasty and can
+*Cons:* `from foo import *` or `import bar.baz.Spar` is very nasty and can
lead to serious maintenance issues because it makes it hard to find module
dependencies.
-*Decision:* Use `import x` for importing packages and modules. Use
-`from x import y` only when `x` is a package and `y` is a module. This
-allows the importer to refer to the module without specifying the full
-package prefix. For example the module `sound.effects.echo` may be
-imported as follows:
+*Decision:* Import only modules. Use `as` to resolve name conflicts if
+necessary. Use `from` for all imports below top-level. Use only absolute
+imports; do not use relative imports. Do not import packages, classes,
+functions, fields, or anything that is not a module.
{{{
+import os
+import sys
+
+from models.graphics import views as graphics_views
+from models.sounds import views as sounds_views
from sound.effects import echo
...
echo.echofilter(input, output, delay=0.7, atten=4)
@@ -150,68 +154,6 @@
without the full package name. This might cause the package to be imported
twice and have unintended side effects.
-The following exception applies: Use of `from foo import Bar as foo_Bar` is allowed, _iff_ Bar is a top-level singleton in foo and foo_Bar is a descriptive name of Bar in relation to foo.
-
-For example, the following is allowed:
-{{{
-from soc.logic.models.user import logic as user_logic
-...
-user_logic.getForCurrentAccount()
-}}}
-
-This is favored over:
-{{{
-from soc.logic import models
-...
-import soc.logic.models.user
-...
-models.logic.user.logic.getForCurrentAccount()
-}}}
-
-
-== Packages ==
-
-*What it is:* Each module is imported and referred to using the full
-pathname location of that module.
-
-*Pros:* Avoids conflicts in module names. Makes it easier to find modules.
-
-*Cons:* Makes it harder to deploy code because you have to replicate the
-package hierarchy.
-
-*Decision:* All new code should refer to modules based on their package
-name. Do not modify `sys.path` or `PYTHONPATH` to import modules from
-other directories. (There may be some situations in which path modification
-is still needed, but this should be avoided if at all possible.)
-
-Imports should be as follows:
-
-{{{
-# Reference in code with complete name.
-import soc.logging
-
-# Reference in code with just module name.
-from soc import logging
-}}}
-
-Some module names might be the same as common local variable names. In
-those cases, to avoid confusion, it sometimes makes sense to only import
-the containing package, and then explicitly import the module. The
-result looks something like this:
-
-{{{
-from soc import models
-import soc.models.user
-
-...
- user = models.user.User()
-}}}
-
-It probably best to avoid module names that lead to this confusion in the
-first place, but sometimes using the obvious module name (such as in the
-`soc.models` package example above) _will_ result in the need for
-workarounds like the one above.
-
== Exceptions ==
*What they are:* Exceptions are a means of breaking out of the normal flow
@@ -1241,8 +1183,8 @@
*Yes:*
{{{
-import sys
import os
+import sys
}}}
*No:*
@@ -1264,32 +1206,18 @@
* SoC-based module imports
* application specific imports
-Sorting should be done alphabetically, with the exception that all lines starting with 'from ...' should come first, an empty line, then all lines starting with 'import ...'. Standard library and third-party library imports that start with 'import ...' should be placed first and separately from each generic group:
+Sorting should be done alphabetically.
{{{
import a_standard
import b_standard
+
import a_third_party
import b_third_party
from a_soc import f
from a_soc import g
-
-import a_soc
-import b_soc
-}}}
-
-Within the import/from lines the statements should be sorted alphabetically:
-
-{{{
-from a import f
-from a import g
-from a.b import h
-from a.d import e
-
-import a.b
-import a.b.c
-import a.d.e
+from b_soc import d
}}}
== Statements ==
@@ -1418,4 +1346,4 @@
_Copyright 2008 Google Inc._
_This work is licensed under a_
[http://soc.googlecode.com/svn/wiki/html/licenses/cc-by-attribution-2_5.html Creative Commons Attribution 2.5 License].
-[http://creativecommons.org/licenses/by/2.5/ http://soc.googlecode.com/svn/wiki/html/licenses/cc-by-2_5-88x31.png]
\ No newline at end of file
+[http://creativecommons.org/licenses/by/2.5/ http://soc.googlecode.com/svn/wiki/html/licenses/cc-by-2_5-88x31.png]
