Raise our own utcnow DeprecationWarning with the right stacklevel

src/_time_machine.c

@@ -110,20 +110,6 @@ _time_machine_utcnow(PyObject *cls, PyObject *args)
     return result;
 }
 
-static PyObject *
-_time_machine_original_utcnow(PyObject *module, PyObject *args)
-{
-    _time_machine_state *state = get_time_machine_state(module);
-
-    PyObject *result = state->original_utcnow(state->datetime_class, args);
-
-    return result;
-}
-PyDoc_STRVAR(original_utcnow_doc,
-    "original_utcnow() -> datetime\n\
-\n\
-Call datetime.datetime.utcnow() after patching.");
-
 /* time.clock_gettime() */
 
 static PyObject *
@@ -565,10 +551,6 @@ static PyMethodDef module_functions[] = {
         (PyCFunction)_time_machine_original_now,
         METH_FASTCALL | METH_KEYWORDS,
         original_now_doc},
-    {"original_utcnow",
-        (PyCFunction)_time_machine_original_utcnow,
-        METH_NOARGS,
-        original_utcnow_doc},
 #if PY_VERSION_HEX >= 0x030d00a2
     {"original_clock_gettime",
         (PyCFunction)_time_machine_original_clock_gettime,

src/time_machine/__init__.py

@@ -330,8 +330,24 @@ def now(tz: dt.tzinfo | None = None) -> dt.datetime:
     return dt.datetime.fromtimestamp(time(), tz)
 
 
+def _deprecated_utcnow(now_utc: dt.datetime, *, stacklevel: int) -> dt.datetime:
+    if sys.version_info >= (3, 12):
+        import warnings
+
+        warnings.warn(
+            "datetime.datetime.utcnow() is deprecated and scheduled for "
+            "removal in a future version. Use timezone-aware "
+            "objects to represent datetimes in UTC: "
+            "datetime.datetime.now(datetime.UTC).",
+            DeprecationWarning,
+            stacklevel=stacklevel + 1,
+        )
+
+    return now_utc.replace(tzinfo=None)
+
+
 def utcnow() -> dt.datetime:
-    return dt.datetime.fromtimestamp(time(), dt.timezone.utc).replace(tzinfo=None)
+    return _deprecated_utcnow(now(dt.timezone.utc), stacklevel=2)
 
 
 # time module
@@ -462,8 +478,8 @@ def now(self, tz: dt.tzinfo | None = None) -> dt.datetime:
         return result
 
     def utcnow(self) -> dt.datetime:
-        result: dt.datetime = _time_machine.original_utcnow()
-        return result
+        now_utc: dt.datetime = _time_machine.original_now(dt.timezone.utc)
+        return _deprecated_utcnow(now_utc, stacklevel=2)
 
 
 class _EscapeHatchDatetime:

tests/test_time_machine.py

@@ -10,6 +10,7 @@
 import uuid
 from contextlib import contextmanager
 from importlib.util import module_from_spec, spec_from_file_location
+from pathlib import Path
 from textwrap import dedent
 from unittest import SkipTest, TestCase, mock
 from zoneinfo import ZoneInfo
@@ -108,7 +109,10 @@ def test_datetime_now_arg():
 
 def test_datetime_utcnow():
     with time_machine.travel(EPOCH):
-        now = dt.datetime.utcnow()
+        with pytest.warns(DeprecationWarning) as w:
+            now = dt.datetime.utcnow()  # warns here
+        line = Path(w[0].filename).read_text().splitlines()[w[0].lineno - 1]
+        assert line.endswith("# warns here")
         assert now.year == 1970
         assert now.month == 1
         assert now.day == 1
@@ -117,12 +121,18 @@ def test_datetime_utcnow():
         assert now.second == 0
         assert now.microsecond == 0
         assert now.tzinfo is None
-    assert dt.datetime.utcnow() >= LIBRARY_EPOCH_DATETIME
+
+    with pytest.warns(DeprecationWarning) as w:
+        real_now = dt.datetime.utcnow()  # warns here
+    line = Path(w[0].filename).read_text().splitlines()[w[0].lineno - 1]
+    assert line.endswith("# warns here")
+    assert real_now >= LIBRARY_EPOCH_DATETIME
 
 
 def test_datetime_utcnow_no_tick():
     with time_machine.travel(EPOCH, tick=False):
-        now = dt.datetime.utcnow()
+        with pytest.warns(DeprecationWarning):
+            now = dt.datetime.utcnow()
         assert now.microsecond == 0
 
 
@@ -1095,10 +1105,16 @@ def test_datetime_now_tz(self):
             assert eh_now >= real_now
 
     def test_datetime_utcnow(self):
-        real_now = dt.datetime.utcnow()
+        with pytest.warns(DeprecationWarning):
+            real_now = dt.datetime.utcnow()
 
         with time_machine.travel(EPOCH):
-            eh_now = time_machine.escape_hatch.datetime.datetime.utcnow()
+            with pytest.warns(DeprecationWarning) as w:
+                eh_now = (
+                    time_machine.escape_hatch.datetime.datetime.utcnow()  # warns here
+                )
+            line = Path(w[0].filename).read_text().splitlines()[w[0].lineno - 1]
+            assert line.endswith("# warns here")
             assert eh_now >= real_now
 
     @py_have_clock_gettime