refactor: privatize local datetime aliases in falcon.util.misc

docs/conf.py

@@ -82,7 +82,7 @@
 
 # General information about the project.
 project = 'Falcon'
-copyright = '{year} Falcon Contributors'.format(year=datetime.utcnow().year)
+copyright = '{year} Falcon Contributors'.format(year=datetime.now().year)
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

falcon/util/misc.py

@@ -74,11 +74,21 @@
 _UNSAFE_CHARS = re.compile(r'[^a-zA-Z0-9.-]')
 
 # PERF(kgriffs): Avoid superfluous namespace lookups
-strptime: Callable[[str, str], datetime.datetime] = datetime.datetime.strptime
-utcnow: Callable[[], datetime.datetime] = functools.partial(
+_strptime: Callable[[str, str], datetime.datetime] = datetime.datetime.strptime
+_utcnow: Callable[[], datetime.datetime] = functools.partial(
     datetime.datetime.now, datetime.timezone.utc
 )
 
+# The above aliases were not underscored prior to Falcon 3.1.2.
+strptime: Callable[[str, str], datetime.datetime] = deprecated(
+    'This was a private alias local to this module; '
+    'please reference datetime.strptime() directly.'
+)(datetime.datetime.strptime)
+utcnow: Callable[[], datetime.datetime] = deprecated(
+    'This was a private alias local to this module; '
+    'please reference datetime.utcnow() directly.'
+)(datetime.datetime.utcnow)
+
 
 # NOTE(kgriffs,vytas): This is tested in the PyPy gate but we do not want devs
 #   to have to install PyPy to check coverage on their workstations, so we use
@@ -134,7 +144,7 @@ def http_now() -> str:
         e.g., 'Tue, 15 Nov 1994 12:45:26 GMT'.
     """
 
-    return dt_to_http(utcnow())
+    return dt_to_http(_utcnow())
 
 
 def dt_to_http(dt: datetime.datetime) -> str:
@@ -178,7 +188,7 @@ def http_date_to_dt(http_date: str, obs_date: bool = False) -> datetime.datetime
         #   over it, and setting up exception handling blocks each
         #   time around the loop, in the case that we don't actually
         #   need to check for multiple formats.
-        return strptime(http_date, '%a, %d %b %Y %H:%M:%S %Z')
+        return _strptime(http_date, '%a, %d %b %Y %H:%M:%S %Z')
 
     time_formats = (
         '%a, %d %b %Y %H:%M:%S %Z',
@@ -190,7 +200,7 @@ def http_date_to_dt(http_date: str, obs_date: bool = False) -> datetime.datetime
     # Loop through the formats and return the first that matches
     for time_format in time_formats:
         try:
-            return strptime(http_date, time_format)
+            return _strptime(http_date, time_format)
         except ValueError:
             continue
 

tests/test_headers.py

@@ -6,7 +6,7 @@
 import falcon
 from falcon import testing
 from falcon.util.deprecation import DeprecatedWarning
-from falcon.util.misc import utcnow
+from falcon.util.misc import _utcnow
 
 from _util import create_app  # NOQA
 
@@ -33,7 +33,7 @@ def __init__(self, last_modified=None):
         if last_modified is not None:
             self.last_modified = last_modified
         else:
-            self.last_modified = utcnow()
+            self.last_modified = _utcnow()
 
     def _overwrite_headers(self, req, resp):
         resp.content_type = 'x-falcon/peregrine'

tests/test_middleware.py

@@ -9,7 +9,7 @@
 import falcon
 import falcon.errors
 import falcon.testing as testing
-from falcon.util.misc import utcnow
+from falcon.util.misc import _utcnow
 
 from _util import create_app  # NOQA
 
@@ -36,15 +36,15 @@ def process_request(self, req, resp):
 class RequestTimeMiddleware:
     def process_request(self, req, resp):
         global context
-        context['start_time'] = utcnow()
+        context['start_time'] = _utcnow()
 
     def process_resource(self, req, resp, resource, params):
         global context
-        context['mid_time'] = utcnow()
+        context['mid_time'] = _utcnow()
 
     def process_response(self, req, resp, resource, req_succeeded):
         global context
-        context['end_time'] = utcnow()
+        context['end_time'] = _utcnow()
         context['req_succeeded'] = req_succeeded
 
     async def process_request_async(self, req, resp):