fix(testing): Restore httpnow

falcon.testing.httpnow was removed by a previous commit. Restore it as an
alias for the sake of backwards compatibility, placing the actual code
in a new function, falcon.util.http_now().

Also update the docs to refer to the utils directly under falcon.*, rather
than falcon.util.* to promote the fact that developers can access them
in that way.

doc/api/util.rst

@@ -22,13 +22,13 @@ Testing
     :members:
 
 .. automodule:: falcon.testing
-    :members: httpnow, rand_string, create_environ
+    :members: rand_string, create_environ
 
 Miscellaneous
 -------------
 
-.. automodule:: falcon.util
-    :members: deprecated, dt_to_http, http_date_to_dt, to_query_str
+.. automodule:: falcon
+    :members: deprecated, http_now, dt_to_http, http_date_to_dt, to_query_str
 
 .. autoclass:: falcon.util.TimezoneGMT
     :members:

falcon/testing/helpers.py

@@ -18,12 +18,16 @@ import sys
 
 import six
 
-from falcon.util import uri
+from falcon.util import uri, http_now
 
 # Constants
 DEFAULT_HOST = 'falconframework.org'
 
 
+# NOTE(kgriffs): Alias for backwards-compatibility with Falcon 0.2
+httpnow = http_now
+
+
 def rand_string(min, max):
     """Returns a randomly-generated string, of a random length.
 

falcon/util/misc.py

@@ -21,6 +21,7 @@ import six
 
 __all__ = (
     'deprecated',
+    'http_now',
     'dt_to_http',
     'http_date_to_dt',
     'to_query_str',
@@ -30,6 +31,7 @@ __all__ = (
 
 # PERF(kgriffs): Avoid superfluous namespace lookups
 strptime = datetime.datetime.strptime
+utcnow = datetime.datetime.utcnow
 
 
 # NOTE(kgriffs): We don't want our deprecations to be ignored by default,
@@ -73,6 +75,17 @@ def deprecated(instructions):
     return decorator
 
 
+def http_now():
+    """Returns the current UTC time as an IMF-fixdate.
+
+    Returns:
+        str: The current UTC time as an IMF-fixdate,
+            e.g., 'Tue, 15 Nov 1994 12:45:26 GMT'.
+    """
+
+    return dt_to_http(utcnow())
+
+
 def dt_to_http(dt):
     """Converts a ``datetime`` instance to an HTTP date string.
 

tests/test_utils.py

@@ -52,6 +52,15 @@ class TestFalconUtils(testtools.TestCase):
         sys.stderr = old_stderr
         self.assertIn(msg, stream.getvalue())
 
+    def test_http_now(self):
+        expected = datetime.utcnow()
+        actual = falcon.http_date_to_dt(falcon.http_now())
+
+        delta = actual - expected
+        delta_sec = abs(delta.days * 86400 + delta.seconds)
+
+        self.assertLessEqual(delta_sec, 1)
+
     def test_dt_to_http(self):
         self.assertEqual(
             falcon.dt_to_http(datetime(2013, 4, 4)),
@@ -286,3 +295,6 @@ class TestFalconTesting(falcon.testing.TestBase):
     def test_decode_empty_result(self):
         body = self.simulate_request('/', decode='utf-8')
         self.assertEqual(body, '')
+
+    def test_httpnow_alias_for_backwards_compat(self):
+        self.assertIs(falcon.testing.httpnow, util.http_now)