From beb0131b089293512c2dab2243b9b2ff314e2387 Mon Sep 17 00:00:00 2001 From: Dennis Fink Date: Wed, 18 Nov 2026 19:18:18 +0100 Subject: feat(core): show relative timestamps Add reusable UTC template filters backed by `humanize` so timestamps render as relative ages while preserving machine-readable `` values. Keep exact UTC timestamps available in tooltips across dashboard, received, sent, detail, and public status views. --- pyproject.toml | 1 + tests/test_init.py | 13 ++++---- tests/test_template_filters.py | 42 ++++++++++++++++++++++++++ uv.lock | 11 +++++++ webmentions_ssg/__init__.py | 4 +++ webmentions_ssg/template_filters.py | 31 +++++++++++++++++++ webmentions_ssg/templates/dashboard.html | 6 ++-- webmentions_ssg/templates/received.html | 17 ++++++----- webmentions_ssg/templates/received_detail.html | 15 ++++++--- webmentions_ssg/templates/sent.html | 10 +++--- webmentions_ssg/templates/sent_source.html | 30 ++++++++++-------- webmentions_ssg/templates/status.html | 10 +++--- 12 files changed, 150 insertions(+), 40 deletions(-) create mode 100644 tests/test_template_filters.py create mode 100644 webmentions_ssg/template_filters.py 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 +# +# 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( + '{{ when | relative_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" in rendered diff --git a/uv.lock b/uv.lock index 2e550e3..91278ba 100644 --- a/uv.lock +++ b/uv.lock @@ -582,6 +582,15 @@ wheels = [ { url = "https://files.pythonhosted.org/packages/f0/0f/310fb31e39e2d734ccaa2c0fb981ee41f7bd5056ce9bc29b2248bd569169/humanfriendly-10.0-py2.py3-none-any.whl", hash = "sha256:1697e1a8a8f550fd43c2865cd84542fc175a61dcb779b6fee18cf6b6ccba1477", size = 86794, upload-time = "2021-09-17T21:40:39.897Z" }, ] +[[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" @@ -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 +# +# 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 Last completed source scan {% if last_scan %} - - {{ last_scan.strftime("%Y-%m-%d %H:%M:%S") }} UTC + + {{ last_scan | relative_time }} {% else %} No completed scan yet 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 {{ webmention.source }} Received - - {{ webmention.created_at.strftime("%Y-%m-%d %H:%M:%S") }} + + {{ webmention.created_at | relative_time }} @@ -203,15 +204,15 @@ SPDX-License-Identifier: BSD-3-Clause {{ webmention.target }} - - {{ webmention.created_at.strftime("%Y-%m-%d %H:%M:%S") }} + + {{ webmention.created_at | relative_time }} - - {{ webmention.updated_at.strftime("%Y-%m-%d %H:%M:%S") }} + + {{ webmention.updated_at | relative_time }} 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 Received - {{ webmention.created_at.strftime("%Y-%m-%d %H:%M:%S") }} UTC + + {{ webmention.created_at | relative_time }} + Last updated - {{ webmention.updated_at.strftime("%Y-%m-%d %H:%M:%S") }} UTC + + {{ webmention.updated_at | relative_time }} + Recovery attempts @@ -128,8 +134,9 @@ SPDX-License-Identifier: BSD-3-Clause {{ event_style.label }} {{ event.action }} - {{ 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 }} Recovery attempts: {{ event.recovery_attempts }} 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 {{ source.sent_webmentions | length }} {{ source.revision }} - - {{ source.created_at.strftime("%Y-%m-%d %H:%M:%S") }} + + {{ source.created_at | relative_time }} - - {{ source.last_seen_at.strftime("%Y-%m-%d %H:%M:%S") }} + + {{ source.last_seen_at | relative_time }} 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 Created at - - {{ source.created_at.strftime("%Y-%m-%d %H:%M:%S") }} + + {{ source.created_at | relative_time }} Last seen at - - {{ source.last_seen_at.strftime("%Y-%m-%d %H:%M:%S") }} + + {{ source.last_seen_at | relative_time }} Revised at - - {{ source.revised_at.strftime("%Y-%m-%d %H:%M:%S") }} + + {{ source.revised_at | relative_time }} Deleted at @@ -72,8 +75,9 @@ SPDX-License-Identifier: BSD-3-Clause {% if source.deleted_at is none %} N/A {% else %} - - {{ source.deleted_at.strftime("%Y-%m-%d %H:%M:%S") }} + + {{ source.deleted_at | relative_time }} {% endif %} @@ -169,8 +173,9 @@ SPDX-License-Identifier: BSD-3-Clause Attempted: {% if webmention.last_attempted_at is not none %} - - {{ webmention.last_attempted_at.strftime("%Y-%m-%d %H:%M:%S") }} + + {{ webmention.last_attempted_at | relative_time }} {% else %} — @@ -180,8 +185,9 @@ SPDX-License-Identifier: BSD-3-Clause Sent: {% if webmention.last_sent_at is not none %} - - {{ webmention.last_sent_at.strftime("%Y-%m-%d %H:%M:%S") }} + + {{ webmention.last_sent_at | relative_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 Received - - {{ webmention.created_at.strftime("%Y-%m-%d %H:%M:%S %Z") }} + + {{ webmention.created_at | relative_time }} Last updated - - {{ webmention.updated_at.strftime("%Y-%m-%d %H:%M:%S %Z") }} + + {{ webmention.updated_at | relative_time }} ID -- cgit v1.3.1
No completed scan yet