From 4142f1d6a3b966eedf5cab40ccb72f7b51571b08 Mon Sep 17 00:00:00 2001
From: Kurt Griffiths <kgriffs@users.noreply.github.com>
Date: Thu, 8 Sep 2016 08:40:39 -0600
Subject: [PATCH] feat(util): Make it easier to reference uri module and
 TimezoneGMT class (#891)

Previously "from falcon import uri" worked but "import falcon.uri" did
not. TimezoneGMT is already available from the front-door falcon
module, but the documentation referenced falcon.util.TimezoneGTM.

Fix this up and update the docs to suit.
---
 docs/api/util.rst       | 16 ++++++++++++----
 falcon/__init__.py      |  6 ++++++
 falcon/util/__init__.py |  2 +-
 3 files changed, 19 insertions(+), 5 deletions(-)

diff --git a/docs/api/util.rst b/docs/api/util.rst
index fa11b32..6604c26 100644
--- a/docs/api/util.rst
+++ b/docs/api/util.rst
@@ -6,14 +6,22 @@ Utilities
 URI Functions
 -------------
 
-.. automodule:: falcon.util.uri
-    :members:
+.. 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
 
 Miscellaneous
 -------------
 
 .. automodule:: falcon
-    :members: deprecated, http_now, dt_to_http, http_date_to_dt, to_query_str
+    :members: deprecated, http_now, dt_to_http, http_date_to_dt,
+        to_query_str, get_http_status, get_bound_method
 
-.. autoclass:: falcon.util.TimezoneGMT
+.. autoclass:: falcon.TimezoneGMT
     :members:
diff --git a/falcon/__init__.py b/falcon/__init__.py
index 7a07607..c5aa051 100644
--- a/falcon/__init__.py
+++ b/falcon/__init__.py
@@ -47,7 +47,13 @@ from falcon.errors import *  # NOQA
 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
 from falcon.util import *  # NOQA
+
 from falcon.hooks import before, after  # NOQA
 from falcon.request import Request, RequestOptions  # NOQA
 from falcon.response import Response  # NOQA
diff --git a/falcon/util/__init__.py b/falcon/util/__init__.py
index 83af49b..553ee59 100644
--- a/falcon/util/__init__.py
+++ b/falcon/util/__init__.py
@@ -13,7 +13,7 @@ imported directly into the front-door `falcon` module for convenience::
 
 Conversely, the `uri` module must be imported explicitly::
 
-    from falcon.util import uri
+    from falcon import uri
 
     some_uri = '...'
     decoded_uri = uri.decode(some_uri)