aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorDennis Fink2026-11-18 19:18:18 +0100
committerDennis Fink2026-11-18 19:18:18 +0100
commitbeb0131b089293512c2dab2243b9b2ff314e2387 (patch)
tree2690eaa17c689a77bccdc1268e971a96ec0e368f
parente3e195ea07fd57288d32c842689ebed7fba636f0 (diff)
downloadwebmentions-ssg-beb0131b089293512c2dab2243b9b2ff314e2387.tar.gz
webmentions-ssg-beb0131b089293512c2dab2243b9b2ff314e2387.zip
feat(core): show relative timestamps
Add reusable UTC template filters backed by `humanize` so timestamps render as relative ages while preserving machine-readable `<time datetime>` values. Keep exact UTC timestamps available in tooltips across dashboard, received, sent, detail, and public status views.
Diffstat (limited to '')
-rw-r--r--pyproject.toml1
-rw-r--r--tests/test_init.py13
-rw-r--r--tests/test_template_filters.py42
-rw-r--r--uv.lock11
-rw-r--r--webmentions_ssg/__init__.py4
-rw-r--r--webmentions_ssg/template_filters.py31
-rw-r--r--webmentions_ssg/templates/dashboard.html6
-rw-r--r--webmentions_ssg/templates/received.html17
-rw-r--r--webmentions_ssg/templates/received_detail.html15
-rw-r--r--webmentions_ssg/templates/sent.html10
-rw-r--r--webmentions_ssg/templates/sent_source.html30
-rw-r--r--webmentions_ssg/templates/status.html10
12 files changed, 150 insertions, 40 deletions
diff --git a/pyproject.toml b/pyproject.toml
index 29ed265..de14bb0 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -26,6 +26,7 @@ dependencies = [
"flask-wtf>=1.3.0",
"flask>=3.1.3",
"html5lib>=1.1",
+ "humanize>=4.17.0",
"httpcore>=1.0.9,<1.1",
"httpx>=0.28.1,<0.29",
"huey>=3.4.0",
diff --git a/tests/test_init.py b/tests/test_init.py
index 8f2bbb7..0966b19 100644
--- a/tests/test_init.py
+++ b/tests/test_init.py
@@ -14,12 +14,16 @@ from sqlalchemy import create_engine
from webmentions_ssg import VERSION, create_app, db, huey
from webmentions_ssg.config import TestingConfig
from webmentions_ssg.net import is_http_url
+from webmentions_ssg.template_filters import relative_time, utc_isoformat, utc_timestamp
def test_create_app_registers_blueprint_and_extensions(app: Flask) -> None:
assert "webmentions" in app.blueprints
assert app.extensions["huey"] is huey
assert app.jinja_env.filters["is_http_url"] is is_http_url
+ assert app.jinja_env.filters["relative_time"] is relative_time
+ assert app.jinja_env.filters["utc_isoformat"] is utc_isoformat
+ assert app.jinja_env.filters["utc_timestamp"] is utc_timestamp
def test_create_app_exposes_version_in_templates(app: Flask) -> None:
@@ -53,12 +57,9 @@ assert webmentions_bp.name == 'webmentions'
def test_in_memory_sqlite_enforces_foreign_keys_without_wal(app: Flask) -> None:
- with app.app_context():
- with db.engine.connect() as connection:
- assert connection.exec_driver_sql("PRAGMA foreign_keys").scalar() == 1
- assert (
- connection.exec_driver_sql("PRAGMA journal_mode").scalar() == "memory"
- )
+ with app.app_context(), db.engine.connect() as connection:
+ assert connection.exec_driver_sql("PRAGMA foreign_keys").scalar() == 1
+ assert connection.exec_driver_sql("PRAGMA journal_mode").scalar() == "memory"
def test_file_sqlite_enables_wal_and_foreign_keys(tmp_path: Path) -> None:
diff --git a/tests/test_template_filters.py b/tests/test_template_filters.py
new file mode 100644
index 0000000..a2a0a87
--- /dev/null
+++ b/tests/test_template_filters.py
@@ -0,0 +1,42 @@
+# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Verify relative timestamps and explicit UTC timezone formatting."""
+
+from datetime import UTC, datetime, timedelta, timezone
+
+from flask import Flask
+
+from webmentions_ssg.template_filters import relative_time, utc_isoformat, utc_timestamp
+
+
+def test_utc_timestamp_normalizes_naive_and_offset_aware_values() -> None:
+ expected = "2026-11-16 08:14:03 UTC"
+ iso_expected = "2026-11-16T08:14:03+00:00"
+ naive = datetime(2026, 11, 16, 8, 14, 3)
+ aware = datetime(2026, 11, 16, 10, 14, 3, tzinfo=timezone(timedelta(hours=2)))
+
+ for value in (naive, aware):
+ assert utc_isoformat(value) == iso_expected
+ assert utc_timestamp(value) == expected
+
+
+def test_relative_time_humanizes_both_aware_and_naive_utc_values() -> None:
+ three_minutes_ago = datetime.now(UTC) - timedelta(minutes=3, seconds=5)
+
+ assert relative_time(three_minutes_ago) == "3 minutes ago"
+ assert relative_time(three_minutes_ago.replace(tzinfo=None)) == "3 minutes ago"
+
+
+def test_template_timestamp_is_relative_with_full_utc_tooltip(app: Flask) -> None:
+ when = datetime.now(UTC) - timedelta(minutes=3, seconds=5)
+ template = app.jinja_env.from_string(
+ '<time datetime="{{ when | utc_isoformat }}" '
+ 'title="{{ when | utc_timestamp }}">{{ when | relative_time }}</time>'
+ )
+
+ rendered = template.render(when=when)
+ assert f'datetime="{when.isoformat()}"' in rendered
+ assert f'title="{when.strftime("%Y-%m-%d %H:%M:%S UTC")}"' in rendered
+ assert ">3 minutes ago</time>" in rendered
diff --git a/uv.lock b/uv.lock
index 2e550e3..91278ba 100644
--- a/uv.lock
+++ b/uv.lock
@@ -583,6 +583,15 @@ wheels = [
]
[[package]]
+name = "humanize"
+version = "4.17.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/d0/a7/5391f6db94bf16289ca63ce2632eef2eba7b9991e701016ac66f04539d47/humanize-4.17.0.tar.gz", hash = "sha256:1d6a36c453dbfbb3f0b34601d2e0b4ce5d48d780305cd45714843f0068fde6ac" }
+wheels = [
+ { url = "https://files.pythonhosted.org/packages/0c/74/bb970f876202aa0e8c4a1e9904f0b3482e73c752512962b7e957091d5acf/humanize-4.17.0-py3-none-any.whl", hash = "sha256:02d0899527760efe18011944f882df4970943b4cdff7b5a0ba7fed43a576ef98" },
+]
+
+[[package]]
name = "idna"
version = "3.20"
source = { registry = "https://pypi.org/simple" }
@@ -1295,6 +1304,7 @@ dependencies = [
{ name = "flask-sqlalchemy" },
{ name = "flask-wtf" },
{ name = "html5lib" },
+ { name = "humanize" },
{ name = "httpcore" },
{ name = "httpx" },
{ name = "huey" },
@@ -1370,6 +1380,7 @@ requires-dist = [
{ name = "flask-sqlalchemy", specifier = ">=3.1.1" },
{ name = "flask-wtf", specifier = ">=1.3.0" },
{ name = "html5lib", specifier = ">=1.1" },
+ { name = "humanize", specifier = ">=4.17.0" },
{ name = "httpcore", specifier = ">=1.0.9,<1.1" },
{ name = "httpx", specifier = ">=0.28.1,<0.29" },
{ name = "huey", specifier = ">=3.4.0" },
diff --git a/webmentions_ssg/__init__.py b/webmentions_ssg/__init__.py
index 174250e..b4b9f72 100644
--- a/webmentions_ssg/__init__.py
+++ b/webmentions_ssg/__init__.py
@@ -23,6 +23,7 @@ from .config import (
)
from .extensions import bootstrap, csrf, db, huey, limiter, mail, migrate
from .net import is_http_url
+from .template_filters import relative_time, utc_isoformat, utc_timestamp
from .version import APP_NAME as APP_NAME
from .version import VERSION
from .views import webmentions_bp
@@ -140,6 +141,9 @@ def create_app(config_class: type[DefaultConfig] | None = None) -> Flask:
return {"VERSION": VERSION}
app.add_template_filter(is_http_url)
+ app.add_template_filter(relative_time)
+ app.add_template_filter(utc_isoformat)
+ app.add_template_filter(utc_timestamp)
app.register_blueprint(webmentions_bp)
diff --git a/webmentions_ssg/template_filters.py b/webmentions_ssg/template_filters.py
new file mode 100644
index 0000000..e6cac2d
--- /dev/null
+++ b/webmentions_ssg/template_filters.py
@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: 2026 Dennis Fink <me+coding@dennisfink.me>
+#
+# SPDX-License-Identifier: BSD-3-Clause
+
+"""Helpers for displaying UTC timestamps in templates."""
+
+from datetime import UTC, datetime
+
+import humanize
+
+
+def as_utc(value: datetime) -> datetime:
+ """Normalize a timestamp to UTC, treating timezone-naive DB values as UTC."""
+ if value.tzinfo is None:
+ return value.replace(tzinfo=UTC)
+ return value.astimezone(UTC)
+
+
+def utc_isoformat(value: datetime) -> str:
+ """Return an unambiguous machine-readable timestamp for the time element."""
+ return as_utc(value).isoformat()
+
+
+def utc_timestamp(value: datetime) -> str:
+ """Return the complete UTC timestamp for the hover tooltip."""
+ return as_utc(value).strftime("%Y-%m-%d %H:%M:%S UTC")
+
+
+def relative_time(value: datetime) -> str:
+ """Render a timestamp as a human-readable age relative to the current UTC time."""
+ return humanize.naturaltime(datetime.now(UTC) - as_utc(value))
diff --git a/webmentions_ssg/templates/dashboard.html b/webmentions_ssg/templates/dashboard.html
index 70e2bf0..b020d46 100644
--- a/webmentions_ssg/templates/dashboard.html
+++ b/webmentions_ssg/templates/dashboard.html
@@ -118,8 +118,10 @@ SPDX-License-Identifier: BSD-3-Clause
<div class="card-body">
<h3 class="h6 text-body-secondary">Last completed source scan</h3>
{% if last_scan %}
- <time datetime="{{ last_scan.isoformat() }}" class="fs-5">
- {{ last_scan.strftime("%Y-%m-%d %H:%M:%S") }} UTC
+ <time datetime="{{ last_scan | utc_isoformat }}"
+ class="fs-5"
+ title="{{ last_scan | utc_timestamp }}">
+ {{ last_scan | relative_time }}
</time>
{% else %}
<p class="text-body-secondary mb-0">No completed scan yet</p>
diff --git a/webmentions_ssg/templates/received.html b/webmentions_ssg/templates/received.html
index 2edf881..8931601 100644
--- a/webmentions_ssg/templates/received.html
+++ b/webmentions_ssg/templates/received.html
@@ -194,8 +194,9 @@ SPDX-License-Identifier: BSD-3-Clause
<a href="{{ webmention.source }}">{{ webmention.source }}</a>
<div class="small mt-1 d-md-none">
Received
- <time datetime="{{ webmention.created_at.isoformat() }}">
- {{ webmention.created_at.strftime("%Y-%m-%d %H:%M:%S") }}
+ <time datetime="{{ webmention.created_at | utc_isoformat }}"
+ title="{{ webmention.created_at | utc_timestamp }}">
+ {{ webmention.created_at | relative_time }}
</time>
</div>
</td>
@@ -203,15 +204,15 @@ SPDX-License-Identifier: BSD-3-Clause
<a href="{{ webmention.target }}">{{ webmention.target }}</a>
</td>
<td class="text-nowrap d-none d-md-table-cell">
- <time datetime="{{ webmention.created_at.isoformat() }}"
- title="{{ webmention.created_at.strftime('%Y-%m-%d %H:%M:%S') }} UTC">
- {{ webmention.created_at.strftime("%Y-%m-%d %H:%M:%S") }}
+ <time datetime="{{ webmention.created_at | utc_isoformat }}"
+ title="{{ webmention.created_at | utc_timestamp }}">
+ {{ webmention.created_at | relative_time }}
</time>
</td>
<td class="text-nowrap d-none d-md-table-cell">
- <time datetime="{{ webmention.updated_at.isoformat() }}"
- title="{{ webmention.updated_at.strftime('%Y-%m-%d %H:%M:%S') }} UTC">
- {{ webmention.updated_at.strftime("%Y-%m-%d %H:%M:%S") }}
+ <time datetime="{{ webmention.updated_at | utc_isoformat }}"
+ title="{{ webmention.updated_at | utc_timestamp }}">
+ {{ webmention.updated_at | relative_time }}
</time>
</td>
<td>
diff --git a/webmentions_ssg/templates/received_detail.html b/webmentions_ssg/templates/received_detail.html
index 32d3e05..38830bf 100644
--- a/webmentions_ssg/templates/received_detail.html
+++ b/webmentions_ssg/templates/received_detail.html
@@ -58,11 +58,17 @@ SPDX-License-Identifier: BSD-3-Clause
</dd>
<dt class="col-md-3">Received</dt>
<dd class="col-md-9">
- <time datetime="{{ webmention.created_at.isoformat() }}">{{ webmention.created_at.strftime("%Y-%m-%d %H:%M:%S") }} UTC</time>
+ <time datetime="{{ webmention.created_at | utc_isoformat }}"
+ title="{{ webmention.created_at | utc_timestamp }}">
+ {{ webmention.created_at | relative_time }}
+ </time>
</dd>
<dt class="col-md-3">Last updated</dt>
<dd class="col-md-9">
- <time datetime="{{ webmention.updated_at.isoformat() }}">{{ webmention.updated_at.strftime("%Y-%m-%d %H:%M:%S") }} UTC</time>
+ <time datetime="{{ webmention.updated_at | utc_isoformat }}"
+ title="{{ webmention.updated_at | utc_timestamp }}">
+ {{ webmention.updated_at | relative_time }}
+ </time>
</dd>
<dt class="col-md-3">Recovery attempts</dt>
<dd class="col-md-9">
@@ -128,8 +134,9 @@ SPDX-License-Identifier: BSD-3-Clause
<span class="badge {{ event_style.badge }}">{{ event_style.label }}</span>
<strong>{{ event.action }}</strong>
<time class="ms-auto text-body-secondary small"
- datetime="{{ event.occurred_at.isoformat() }}">
- {{ event.occurred_at.strftime("%Y-%m-%d %H:%M:%S") }} UTC
+ datetime="{{ event.occurred_at | utc_isoformat }}"
+ title="{{ event.occurred_at | utc_timestamp }}">
+ {{ event.occurred_at | relative_time }}
</time>
</div>
<div class="small text-body-secondary">Recovery attempts: {{ event.recovery_attempts }}</div>
diff --git a/webmentions_ssg/templates/sent.html b/webmentions_ssg/templates/sent.html
index d949f01..d2a319d 100644
--- a/webmentions_ssg/templates/sent.html
+++ b/webmentions_ssg/templates/sent.html
@@ -58,13 +58,15 @@ SPDX-License-Identifier: BSD-3-Clause
<td>{{ source.sent_webmentions | length }}</td>
<td class="d-none d-md-table-cell">{{ source.revision }}</td>
<td class="text-nowrap d-none d-md-table-cell">
- <time datetime="{{ source.created_at.isoformat() }}">
- {{ source.created_at.strftime("%Y-%m-%d %H:%M:%S") }}
+ <time datetime="{{ source.created_at | utc_isoformat }}"
+ title="{{ source.created_at | utc_timestamp }}">
+ {{ source.created_at | relative_time }}
</time>
</td>
<td class="text-nowrap d-none d-md-table-cell">
- <time datetime="{{ source.last_seen_at.isoformat() }}">
- {{ source.last_seen_at.strftime("%Y-%m-%d %H:%M:%S") }}
+ <time datetime="{{ source.last_seen_at | utc_isoformat }}"
+ title="{{ source.last_seen_at | utc_timestamp }}">
+ {{ source.last_seen_at | relative_time }}
</time>
</td>
<td>
diff --git a/webmentions_ssg/templates/sent_source.html b/webmentions_ssg/templates/sent_source.html
index 6e34458..33e26a2 100644
--- a/webmentions_ssg/templates/sent_source.html
+++ b/webmentions_ssg/templates/sent_source.html
@@ -51,20 +51,23 @@ SPDX-License-Identifier: BSD-3-Clause
</dd>
<dt class="col-sm-2">Created at</dt>
<dd class="col-sm-4">
- <time datetime="{{ source.created_at.isoformat() }}">
- {{ source.created_at.strftime("%Y-%m-%d %H:%M:%S") }}
+ <time datetime="{{ source.created_at | utc_isoformat }}"
+ title="{{ source.created_at | utc_timestamp }}">
+ {{ source.created_at | relative_time }}
</time>
</dd>
<dt class="col-sm-2">Last seen at</dt>
<dd class="col-sm-4">
- <time datetime="{{ source.last_seen_at.isoformat() }}">
- {{ source.last_seen_at.strftime("%Y-%m-%d %H:%M:%S") }}
+ <time datetime="{{ source.last_seen_at | utc_isoformat }}"
+ title="{{ source.last_seen_at | utc_timestamp }}">
+ {{ source.last_seen_at | relative_time }}
</time>
</dd>
<dt class="col-sm-2">Revised at</dt>
<dd class="col-sm-4">
- <time datetime="{{ source.revised_at.isoformat() }}">
- {{ source.revised_at.strftime("%Y-%m-%d %H:%M:%S") }}
+ <time datetime="{{ source.revised_at | utc_isoformat }}"
+ title="{{ source.revised_at | utc_timestamp }}">
+ {{ source.revised_at | relative_time }}
</time>
</dd>
<dt class="col-sm-2">Deleted at</dt>
@@ -72,8 +75,9 @@ SPDX-License-Identifier: BSD-3-Clause
{% if source.deleted_at is none %}
N/A
{% else %}
- <time datetime="{{ source.deleted_at.isoformat() }}">
- {{ source.deleted_at.strftime("%Y-%m-%d %H:%M:%S") }}
+ <time datetime="{{ source.deleted_at | utc_isoformat }}"
+ title="{{ source.deleted_at | utc_timestamp }}">
+ {{ source.deleted_at | relative_time }}
</time>
{% endif %}
</dd>
@@ -169,8 +173,9 @@ SPDX-License-Identifier: BSD-3-Clause
<strong>Attempted:</strong>
<br>
{% if webmention.last_attempted_at is not none %}
- <time datetime="{{ webmention.last_attempted_at.isoformat() }}">
- {{ webmention.last_attempted_at.strftime("%Y-%m-%d %H:%M:%S") }}
+ <time datetime="{{ webmention.last_attempted_at | utc_isoformat }}"
+ title="{{ webmention.last_attempted_at | utc_timestamp }}">
+ {{ webmention.last_attempted_at | relative_time }}
</time>
{% else %}
—
@@ -180,8 +185,9 @@ SPDX-License-Identifier: BSD-3-Clause
<strong>Sent:</strong>
<br>
{% if webmention.last_sent_at is not none %}
- <time datetime="{{ webmention.last_sent_at.isoformat() }}">
- {{ webmention.last_sent_at.strftime("%Y-%m-%d %H:%M:%S") }}
+ <time datetime="{{ webmention.last_sent_at | utc_isoformat }}"
+ title="{{ webmention.last_sent_at | utc_timestamp }}">
+ {{ webmention.last_sent_at | relative_time }}
</time>
{% else %}
—
diff --git a/webmentions_ssg/templates/status.html b/webmentions_ssg/templates/status.html
index a9a39b4..27821ff 100644
--- a/webmentions_ssg/templates/status.html
+++ b/webmentions_ssg/templates/status.html
@@ -44,14 +44,16 @@ SPDX-License-Identifier: BSD-3-Clause
</dd>
<dt class="col-sm-3">Received</dt>
<dd class="col-sm-9">
- <time datetime="{{ webmention.created_at.isoformat() }}">
- {{ webmention.created_at.strftime("%Y-%m-%d %H:%M:%S %Z") }}
+ <time datetime="{{ webmention.created_at | utc_isoformat }}"
+ title="{{ webmention.created_at | utc_timestamp }}">
+ {{ webmention.created_at | relative_time }}
</time>
</dd>
<dt class="col-sm-3">Last updated</dt>
<dd class="col-sm-9">
- <time datetime="{{ webmention.updated_at.isoformat() }}">
- {{ webmention.updated_at.strftime("%Y-%m-%d %H:%M:%S %Z") }}
+ <time datetime="{{ webmention.updated_at | utc_isoformat }}"
+ title="{{ webmention.updated_at | utc_timestamp }}">
+ {{ webmention.updated_at | relative_time }}
</time>
</dd>
<dt class="col-sm-3">ID</dt>