From 815daa17f2fdea87bba09c44d0bbda0d565aebe5 Mon Sep 17 00:00:00 2001 From: Sylvain Lesage Date: Thu, 22 Aug 2024 01:30:15 +0000 Subject: [PATCH] add comments --- libs/libcommon/src/libcommon/queue/dataset_blockages.py | 1 + libs/libcommon/src/libcommon/queue/jobs.py | 7 +++++-- libs/libcommon/src/libcommon/queue/lock.py | 8 ++++++-- libs/libcommon/src/libcommon/queue/metrics.py | 4 +++- libs/libcommon/src/libcommon/queue/past_jobs.py | 1 + libs/libcommon/src/libcommon/simple_cache.py | 1 + 6 files changed, 17 insertions(+), 5 deletions(-) diff --git a/libs/libcommon/src/libcommon/queue/dataset_blockages.py b/libs/libcommon/src/libcommon/queue/dataset_blockages.py index a5791c9b5b..c0cf4134c1 100644 --- a/libs/libcommon/src/libcommon/queue/dataset_blockages.py +++ b/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 = { diff --git a/libs/libcommon/src/libcommon/queue/jobs.py b/libs/libcommon/src/libcommon/queue/jobs.py index 5c0bf9e489..b9b1092d23 100644 --- a/libs/libcommon/src/libcommon/queue/jobs.py +++ b/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 = { diff --git a/libs/libcommon/src/libcommon/queue/lock.py b/libs/libcommon/src/libcommon/queue/lock.py index 7f0486e3a5..15ab16b497 100644 --- a/libs/libcommon/src/libcommon/queue/lock.py +++ b/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"]() diff --git a/libs/libcommon/src/libcommon/queue/metrics.py b/libs/libcommon/src/libcommon/queue/metrics.py index b38d2711f2..73839a3f33 100644 --- a/libs/libcommon/src/libcommon/queue/metrics.py +++ b/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) diff --git a/libs/libcommon/src/libcommon/queue/past_jobs.py b/libs/libcommon/src/libcommon/queue/past_jobs.py index 4268f46854..62e9533c5d 100644 --- a/libs/libcommon/src/libcommon/queue/past_jobs.py +++ b/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 = { diff --git a/libs/libcommon/src/libcommon/simple_cache.py b/libs/libcommon/src/libcommon/simple_cache.py index cbc38526e5..8f911788a8 100644 --- a/libs/libcommon/src/libcommon/simple_cache.py +++ b/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.