From 83fa288731d3d5132c95b81a989c23cb37a4f98b Mon Sep 17 00:00:00 2001
From: Kurt Griffiths <kurt.griffiths@rackspace.com>
Date: Wed, 22 Apr 2015 20:53:28 -0500
Subject: [PATCH] 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          |  6 +++---
 falcon/testing/helpers.py |  6 +++++-
 falcon/util/misc.py       | 13 +++++++++++++
 tests/test_utils.py       | 10 ++++++++++
 4 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/doc/api/util.rst b/doc/api/util.rst
index 386d5f052..46ab3b6fe 100644
--- a/doc/api/util.rst
+++ b/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:
diff --git a/falcon/testing/helpers.py b/falcon/testing/helpers.py
index 5e1dfb0cc..531e4800c 100644
--- a/falcon/testing/helpers.py
+++ b/falcon/testing/helpers.py
@@ -18,12 +18,16 @@
 
 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.
 
diff --git a/falcon/util/misc.py b/falcon/util/misc.py
index ebfefcf93..827ecf318 100644
--- a/falcon/util/misc.py
+++ b/falcon/util/misc.py
@@ -21,6 +21,7 @@
 
 __all__ = (
     'deprecated',
+    'http_now',
     'dt_to_http',
     'http_date_to_dt',
     'to_query_str',
@@ -30,6 +31,7 @@
 
 # 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 wrapper(*args, **kwargs):
     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.
 
diff --git a/tests/test_utils.py b/tests/test_utils.py
index b5a0d350c..10c00dff0 100644
--- a/tests/test_utils.py
+++ b/tests/test_utils.py
@@ -52,6 +52,13 @@ def old_thing():
         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
+        self.assertLessEqual(delta.total_seconds(), 2)
+
     def test_dt_to_http(self):
         self.assertEqual(
             falcon.dt_to_http(datetime(2013, 4, 4)),
@@ -286,3 +293,6 @@ def test_none_header_value_in_create_environ(self):
     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)