Rejiggered convenience import so setup.py works without Paramiko inst…

…alled.

docs/usage.rst

@@ -7,16 +7,16 @@ Importing Fabric itself
 
 Simplest method, which is not PEP8-compliant (meaning it's not best practices)::
 
-    from fabric import *
+    from fabric.api import *
 
 Slightly better, albeit verbose, method which *is* PEP8-compliant::
 
-    from fabric import run, sudo, prompt, abort
+    from fabric.api import run, sudo, prompt, abort, ...
 
 .. note::
     You can also import directly from the individual submodules, e.g.
     ``from fabric.utils import abort``. However, all of Fabric's public API is
-    guaranteed to be available at the package level for convenience purposes.
+    guaranteed to be available via `fabric.api` for convenience purposes.
 
 Importing other modules
 =======================
@@ -36,7 +36,7 @@ data out of a webservice::
 
     from urllib import urlopen
 
-    from fabric import run
+    from fabric.api import run
 
     def my_task():
         """

fabric/__init__.py

@@ -1,6 +1,4 @@
-from context_managers import warnings_only
-from decorators import hosts, roles, runs_once
-from operations import require, prompt, put, get, run, sudo, local
-from state import env
-from utils import abort, warn
+"""
+See `fabric.api` for the publically importable API.
+"""
 from version import get_version

fabric/api.py

@@ -0,0 +1,13 @@
+"""
+Non-init module for doing convenient * imports from.
+
+Necessary because if we did this in __init__, one would be unable to import
+anything else inside the package -- like, say, the version number used in
+setup.py -- without triggering loads of most of the code. Which doesn't work so
+well when you're using setup.py to install e.g. paramiko!
+"""
+from context_managers import warnings_only
+from decorators import hosts, roles, runs_once
+from operations import require, prompt, put, get, run, sudo, local
+from state import env
+from utils import abort, warn