add comments

libs/libcommon/src/libcommon/queue/dataset_blockages.py

@@ -49,6 +49,7 @@ class DatasetBlockageDocument(Document):
     Args:
         dataset (`str`): The dataset on which to apply the job.
         blocked_at (`datetime`): The date the dataset has been blocked.
+          When read, it's an offset-naive datetime. Use pytz.UTC.localize() to make it timezone-aware.
     """
 
     meta = {

libs/libcommon/src/libcommon/queue/jobs.py

@@ -152,9 +152,12 @@ class JobDocument(Document):
         priority (`Priority`, *optional*): The priority of the job. Defaults to Priority.LOW.
         status (`Status`, *optional*): The status of the job. Defaults to Status.WAITING.
         difficulty (`int`): The difficulty of the job: 1=easy, 100=hard as a convention (strictly positive integer).
-        created_at (`datetime`): The creation date of the job.
-        started_at (`datetime`, *optional*): When the job has started.
+        created_at (`datetime`): The creation date of the job. When read, it's an offset-naive datetime.
+          Use pytz.UTC.localize() to make it timezone-aware.
+        started_at (`datetime`, *optional*): When the job has started. When read, it's an offset-naive datetime.
+          Use pytz.UTC.localize() to make it timezone-aware.
         last_heartbeat (`datetime`, *optional*): Last time the running job got a heartbeat from the worker.
+          When read, it's an offset-naive datetime. Use pytz.UTC.localize() to make it timezone-aware.
     """
 
     meta = {

libs/libcommon/src/libcommon/queue/lock.py

@@ -79,8 +79,12 @@ class Lock(Document):
     ttl = IntField()
     job_id = StringField()  # deprecated
 
-    created_at = DateTimeField()
-    updated_at = DateTimeField()
+    created_at = (
+        DateTimeField()
+    )  # When read, it's an offset-naive datetime. Use pytz.UTC.localize() to make it timezone-aware.
+    updated_at = (
+        DateTimeField()
+    )  # When read, it's an offset-naive datetime. Use pytz.UTC.localize() to make it timezone-aware.
 
     objects = QuerySetManager["Lock"]()
 

libs/libcommon/src/libcommon/queue/metrics.py

@@ -54,7 +54,8 @@ class JobTotalMetricDocument(Document):
         status (`str`): job status see libcommon.queue.jobs.Status
         dataset_status (`str`): whether the dataset is blocked ("normal", "blocked")
         total (`int`): total of jobs
-        created_at (`datetime`): when the metric has been created.
+        created_at (`datetime`): when the metric has been created. When read, it's an
+          offset-naive datetime. Use pytz.UTC.localize() to make it timezone-aware.
     """
 
     id = ObjectIdField(db_field="_id", primary_key=True, default=ObjectId)
@@ -84,6 +85,7 @@ class WorkerSizeJobsCountDocument(Document):
         worker_size (`WorkerSize`): worker size
         jobs_count (`int`): jobs count
         created_at (`datetime`): when the metric has been created.
+          When read, it's an offset-naive datetime. Use pytz.UTC.localize() to make it timezone-aware.
     """
 
     id = ObjectIdField(db_field="_id", primary_key=True, default=ObjectId)

libs/libcommon/src/libcommon/queue/past_jobs.py

@@ -55,6 +55,7 @@ class PastJobDocument(Document):
         dataset (`str`): The dataset on which to apply the job.
         duration (`int`): The duration of the job, in seconds.
         finished_at (`datetime`): The date the job has finished.
+          When read, it's an offset-naive datetime. Use pytz.UTC.localize() to make it timezone-aware.
     """
 
     meta = {

libs/libcommon/src/libcommon/simple_cache.py

@@ -131,6 +131,7 @@ class CachedResponseDocument(Document):
         content (`dict`): The content of the cached response. Can be an error or a valid content.
         details (`dict`, *optional*): Additional details, eg. a detailed error that we don't want to send as a response.
         updated_at (`datetime`): When the cache entry has been last updated.
+          When read, it's an offset-naive datetime. Use pytz.UTC.localize() to make it timezone-aware.
         duration (`float`, *optional*): Duration of a corresponding job in seconds.
         job_runner_version (`int`): The version of the job runner that cached the response.
         failed_runs (`int`): The number of failed_runs to get cached result.