diff --git a/docs/api/util.rst b/docs/api/util.rst index 6604c26..9d8400e 100644 --- a/docs/api/util.rst +++ b/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 diff --git a/falcon/__init__.py b/falcon/__init__.py index c5aa051..8c4f092 100644 --- a/falcon/__init__.py +++ b/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 diff --git a/falcon/uri.py b/falcon/uri.py new file mode 100644 index 0000000..7b854bc --- /dev/null +++ b/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 diff --git a/tox.ini b/tox.ini index 61fea1e..bb34d61 100644 --- a/tox.ini +++ b/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 []