feat(config): add STATS_EVENTS_USE_NAIVE_UTC_DATETIME flag

Introduce STATS_EVENTS_USE_NAIVE_UTC_DATETIME (default: True) to strip
tzinfo from event timestamps at build time. Set to False to opt-in to
timezone-aware UTC datetimes.

Author: zzacharo

invenio_stats/config.py

@@ -76,3 +76,11 @@
 
 Default behaviour will register the templates as search templates.
 """
+
+STATS_EVENTS_USE_NAIVE_UTC_DATETIME = True
+"""Use naive UTC datetimes (without tzinfo) when building event timestamps.
+
+When set to ``True`` (default), the ``tzinfo`` will be stripped from the UTC
+datetime used as the event timestamp (i.e. ``datetime.replace(tzinfo=None)``
+is applied). Set to ``False`` to opt-in to timezone-aware UTC datetimes.
+"""

invenio_stats/contrib/event_builders.py

@@ -12,17 +12,25 @@
 
 import datetime
 
-from flask import request
+from flask import current_app, request
 
 from ..utils import get_user
 
 
+def _build_timestamp():
+    """Build an event timestamp, stripping tzinfo if configured."""
+    ts = datetime.datetime.now(datetime.timezone.utc)
+    if current_app.config["STATS_EVENTS_USE_NAIVE_UTC_DATETIME"]:
+        ts = ts.replace(tzinfo=None)
+    return ts.isoformat()
+
+
 def file_download_event_builder(event, sender_app, obj=None, **kwargs):
     """Build a file-download event."""
     event.update(
         {
             # When:
-            "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+            "timestamp": _build_timestamp(),
             # What:
             "bucket_id": str(obj.bucket_id),
             "file_id": str(obj.file_id),
@@ -53,7 +61,7 @@ def record_view_event_builder(event, sender_app, pid=None, record=None, **kwargs
     event.update(
         {
             # When:
-            "timestamp": datetime.datetime.now(datetime.timezone.utc).isoformat(),
+            "timestamp": _build_timestamp(),
             # What:
             "record_id": str(record.id),
             "pid_type": pid.pid_type,

tests/contrib/test_event_builders.py

@@ -43,7 +43,7 @@ def test_file_download_event_builder(app, mock_user_ctx, sequential_ids, objects
             file_download_event_builder(event, app, file_obj)
         assert event == {
             # When:
-            "timestamp": NewDate.now(tzinfo=timezone.utc).isoformat(),
+            "timestamp": NewDate.now(tzinfo=timezone.utc).replace(tzinfo=None).isoformat(),
             # What:
             "bucket_id": str(file_obj.bucket_id),
             "file_id": str(file_obj.file_id),
@@ -63,7 +63,7 @@ def test_record_view_event_builder(app, mock_user_ctx, record, pid):
             record_view_event_builder(event, app, pid, record)
         assert event == {
             # When:
-            "timestamp": NewDate.now(tzinfo=timezone.utc).isoformat(),
+            "timestamp": NewDate.now(tzinfo=timezone.utc).replace(tzinfo=None).isoformat(),
             # What:
             "record_id": str(record.id),
             "pid_type": pid.pid_type,
@@ -72,3 +72,38 @@ def test_record_view_event_builder(app, mock_user_ctx, record, pid):
             # Who:
             **get_user(),
         }
+
+
+def test_file_download_event_builder_aware_datetime(
+    app, mock_user_ctx, sequential_ids, objects
+):
+    """Test file-download event builder produces aware UTC datetime when opted in."""
+    file_obj = objects[0]
+    file_obj.bucket_id = sequential_ids[0]
+
+    app.config["STATS_EVENTS_USE_NAIVE_UTC_DATETIME"] = False
+    try:
+        with app.test_request_context(headers=headers):
+            event = {}
+            with patch("datetime.datetime", NewDate):
+                file_download_event_builder(event, app, file_obj)
+            assert event["timestamp"] == NewDate.now(tzinfo=timezone.utc).isoformat()
+            # Aware ISO format must contain timezone offset
+            assert "+00:00" in event["timestamp"]
+    finally:
+        app.config["STATS_EVENTS_USE_NAIVE_UTC_DATETIME"] = True
+
+
+def test_record_view_event_builder_aware_datetime(app, mock_user_ctx, record, pid):
+    """Test record-view event builder produces aware UTC datetime when opted in."""
+    app.config["STATS_EVENTS_USE_NAIVE_UTC_DATETIME"] = False
+    try:
+        with app.test_request_context(headers=headers):
+            event = {}
+            with patch("datetime.datetime", NewDate):
+                record_view_event_builder(event, app, pid, record)
+            assert event["timestamp"] == NewDate.now(tzinfo=timezone.utc).isoformat()
+            # Aware ISO format must contain timezone offset
+            assert "+00:00" in event["timestamp"]
+    finally:
+        app.config["STATS_EVENTS_USE_NAIVE_UTC_DATETIME"] = True