fix(util): Fix falcon.uri import (#904)

The previous attempt at fixing this failed, and so do something a bit
more evil. We'll remove this later in 2.0 once util goes away and
everything is just implemented under the falcon package directly.

docs/api/util.rst

@@ -6,12 +6,6 @@ Utilities
 URI Functions
 -------------
 
-.. NOTE(kgriffs): Due to the way we have been hoisting uri into falcon,
-.. sphinx can't import just falcon.uri (root cause TBD). Whether or not
-.. the way we are hoisting things is legit (hint: probably not, this
-.. is something to address in Falcon 2.0), sphinx can't handle it
-.. by default so we have a custom extension to fix things up.
-
 .. automodule:: falcon.uri
     :members: encode, encode_value, decode, parse_host,
         parse_query_string, unquote_string

falcon/__init__.py

@@ -48,10 +48,11 @@ from falcon.redirects import *  # NOQA
 from falcon.http_error import HTTPError  # NOQA
 from falcon.http_status import HTTPStatus  # NOQA
 
-# NOTE(kgriffs): Explicitly import uri since the star import doesn't
-# grab modules by default. This is simpler and easier to maintain
-# vs. a large __all__ list in util/__init__.py
-import falcon.util.uri as uri  # NOQA
+# NOTE(kgriffs): Ensure that "from falcon import uri" will import
+# the same front-door module as "import falcon.uri". This works by
+# priming the import cache with the one we want.
+import falcon.uri  # NOQA
+
 from falcon.util import *  # NOQA
 
 from falcon.hooks import before, after  # NOQA

falcon/uri.py

@@ -0,0 +1,16 @@
+"""URI utilities.
+
+This module provides utility functions to parse, encode, decode, and
+otherwise manipulate a URI. These functions are not available directly
+in the `falcon` module, and so must be explicitly imported::
+
+    from falcon import uri
+
+    name, port = uri.parse_host('example.org:8080')
+"""
+
+# NOTE(kgriffs): This module exists to make "import falcon.uri"
+# work. Eventually we will remove the util module and flatten the
+# falcon namespace, but in the meantime...
+
+from falcon.util.uri import *  # NOQA

tox.ini

@@ -187,4 +187,4 @@ commands = falcon-bench []
 deps = -r{toxinidir}/tools/doc-requires
 whitelist_externals = rm
 commands =
-    sphinx-build -j4 -E -b html docs docs/_build/html
+    sphinx-build -j4 -E -b html docs docs/_build/html []