diff options
| author | Dennis Fink | 2026-11-18 19:18:18 +0100 |
|---|---|---|
| committer | Dennis Fink | 2026-11-18 19:18:18 +0100 |
| commit | beb0131b089293512c2dab2243b9b2ff314e2387 (patch) | |
| tree | 2690eaa17c689a77bccdc1268e971a96ec0e368f | |
| parent | e3e195ea07fd57288d32c842689ebed7fba636f0 (diff) | |
| download | webmentions-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.toml | 1 | ||||
| -rw-r--r-- | tests/test_init.py | 13 | ||||
| -rw-r--r-- | tests/test_template_filters.py | 42 | ||||
| -rw-r--r-- | uv.lock | 11 | ||||
| -rw-r--r-- | webmentions_ssg/__init__.py | 4 | ||||
| -rw-r--r-- | webmentions_ssg/template_filters.py | 31 | ||||
| -rw-r--r-- | webmentions_ssg/templates/dashboard.html | 6 | ||||
| -rw-r--r-- | webmentions_ssg/templates/received.html | 17 | ||||
| -rw-r--r-- | webmentions_ssg/templates/received_detail.html | 15 | ||||
| -rw-r--r-- | webmentions_ssg/templates/sent.html | 10 | ||||
| -rw-r--r-- | webmentions_ssg/templates/sent_source.html | 30 | ||||
| -rw-r--r-- | webmentions_ssg/templates/status.html | 10 |
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 @@ -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> |
