From ab0a6e72fe6877291c917539f94e2bb26b7a5084 Mon Sep 17 00:00:00 2001
From: Lance Edgar <lance@wuttaproject.org>
Date: Mon, 29 Dec 2025 14:07:40 -0600
Subject: [PATCH] fix: add `html` flag param for `app.render_datetime()`

---
 src/wuttjamaican/app.py     | 27 +++++++++++++++--
 src/wuttjamaican/testing.py |  4 +--
 tests/test_app.py           | 58 ++++++++++++++++++++-----------------
 3 files changed, 57 insertions(+), 32 deletions(-)

diff --git a/src/wuttjamaican/app.py b/src/wuttjamaican/app.py
index 9f4f41b..a623af8 100644
--- a/src/wuttjamaican/app.py
+++ b/src/wuttjamaican/app.py
@@ -34,6 +34,7 @@ import importlib
 from importlib.metadata import version
 
 import humanize
+from webhelpers2.html import HTML
 
 from wuttjamaican.util import (
     get_timezone_by_name,
@@ -915,7 +916,7 @@ class AppHandler:  # pylint: disable=too-many-public-methods
             return ""
         return value.strftime(self.display_format_date)
 
-    def render_datetime(self, value, local=True):
+    def render_datetime(self, value, local=True, html=False):
         """
         Return a human-friendly display string for the given datetime.
 
@@ -928,13 +929,33 @@ class AppHandler:  # pylint: disable=too-many-public-methods
            :meth:`localtime()` to normalize it for display.  Specify
            ``local=False`` to skip that and render the value as-is.
 
-        :returns: Rendered datetime as string.
+        :param html: If true, return HTML (with tooltip showing
+           relative time delta) instead of plain text.
+
+        :returns: Rendered datetime as string (or HTML with tooltip).
         """
         if value is None:
             return ""
+
+        # we usually want to render a "local" time
         if local:
             value = self.localtime(value)
-        return value.strftime(self.display_format_datetime)
+
+        # simple formatted text
+        text = value.strftime(self.display_format_datetime)
+
+        if html:
+
+            # calculate time diff
+            # nb. if both times are naive, they should be UTC;
+            # otherwise if both are zone-aware, this should work even
+            # if they use different zones.
+            delta = self.make_utc(tzinfo=bool(value.tzinfo)) - value
+
+            # show text w/ time diff as tooltip
+            return HTML.tag("span", c=text, title=self.render_time_ago(delta))
+
+        return text
 
     def render_error(self, error):
         """
diff --git a/src/wuttjamaican/testing.py b/src/wuttjamaican/testing.py
index 76a1da0..59db454 100644
--- a/src/wuttjamaican/testing.py
+++ b/src/wuttjamaican/testing.py
@@ -105,9 +105,9 @@ class FileTestCase(TestCase):
             f.write(content)
         return path
 
-    def mkdir(  # pragma: no cover; pylint: disable=unused-argument,empty-docstring
+    def mkdir(
         self, dirname
-    ):
+    ):  # pragma: no cover; pylint: disable=unused-argument,empty-docstring
         """ """
         warnings.warn(
             "FileTestCase.mkdir() is deprecated; "
diff --git a/tests/test_app.py b/tests/test_app.py
index bf51576..3693b2d 100644
--- a/tests/test_app.py
+++ b/tests/test_app.py
@@ -595,38 +595,42 @@ app_title = WuttaTest
         self.assertEqual(self.app.render_date(dt), "2024-12-11")
 
     def test_render_datetime(self):
+        self.config.setdefault("wuttatest.timezone.default", "America/Los_Angeles")
         tzlocal = get_timezone_by_name("America/Los_Angeles")
-        with patch.object(self.app, "get_timezone", return_value=tzlocal):
 
-            # null value
-            self.assertEqual(self.app.render_datetime(None), "")
+        # null value
+        self.assertEqual(self.app.render_datetime(None), "")
 
-            # naive UTC
-            dt = datetime.datetime(2024, 12, 17, 1, 12)
-            self.assertEqual(
-                self.app.render_datetime(dt, local=True), "2024-12-16 17:12-0800"
-            )
-            self.assertEqual(
-                self.app.render_datetime(dt, local=False), "2024-12-17 01:12"
-            )
+        # naive UTC
+        dt = datetime.datetime(2024, 12, 17, 1, 12)
+        self.assertEqual(
+            self.app.render_datetime(dt, local=True), "2024-12-16 17:12-0800"
+        )
+        self.assertEqual(self.app.render_datetime(dt, local=False), "2024-12-17 01:12")
 
-            # aware UTC
-            dt = datetime.datetime(2024, 12, 17, 1, 12, tzinfo=datetime.timezone.utc)
-            self.assertEqual(
-                self.app.render_datetime(dt, local=True), "2024-12-16 17:12-0800"
-            )
-            self.assertEqual(
-                self.app.render_datetime(dt, local=False), "2024-12-17 01:12+0000"
-            )
+        # aware UTC
+        dt = datetime.datetime(2024, 12, 17, 1, 12, tzinfo=datetime.timezone.utc)
+        self.assertEqual(
+            self.app.render_datetime(dt, local=True), "2024-12-16 17:12-0800"
+        )
+        self.assertEqual(
+            self.app.render_datetime(dt, local=False), "2024-12-17 01:12+0000"
+        )
 
-            # aware local
-            dt = datetime.datetime(2024, 12, 16, 19, 12, tzinfo=tzlocal)
-            self.assertEqual(
-                self.app.render_datetime(dt, local=True), "2024-12-16 19:12-0800"
-            )
-            self.assertEqual(
-                self.app.render_datetime(dt, local=False), "2024-12-16 19:12-0800"
-            )
+        # aware local
+        dt = datetime.datetime(2024, 12, 16, 19, 12, tzinfo=tzlocal)
+        self.assertEqual(
+            self.app.render_datetime(dt, local=True), "2024-12-16 19:12-0800"
+        )
+        self.assertEqual(
+            self.app.render_datetime(dt, local=False), "2024-12-16 19:12-0800"
+        )
+
+        # as html
+        dt = datetime.datetime(2024, 12, 16, 19, 12, tzinfo=tzlocal)
+        html = self.app.render_datetime(dt, local=True, html=True)
+        self.assertTrue(html.startswith('<span title="'))
+        self.assertIn("2024-12-16 19:12-0800", html)
 
     def test_render_error(self):