From f50f5d5c2ce1667362dfffd654c211ceaa4caf23 Mon Sep 17 00:00:00 2001
From: Fabio Buso <fabio@hopsworks.ai>
Date: Mon, 16 Oct 2023 01:39:30 +0200
Subject: [PATCH] Add method documentation:

---
 python/hopsworks/core/job_api.py |  5 +++--
 python/hopsworks/job.py          | 28 +++++++++++++++++++++++++++-
 2 files changed, 30 insertions(+), 3 deletions(-)

diff --git a/python/hopsworks/core/job_api.py b/python/hopsworks/core/job_api.py
index d36848943..e40afe8c0 100644
--- a/python/hopsworks/core/job_api.py
+++ b/python/hopsworks/core/job_api.py
@@ -196,11 +196,12 @@ def _update_job(self, name: str, config: dict):
     def _schedule_job(self, name, schedule_config):
         _client = client.get_instance()
         path_params = ["project", self._project_id, "jobs", name, "schedule", "v2"]
-
         headers = {"content-type": "application/json"}
+        method = "PUT" if schedule_config["id"] else "POST"
+
         return job_schedule.JobSchedule.from_response_json(
             _client._send_request(
-                "POST", path_params, headers=headers, data=json.dumps(schedule_config)
+                method, path_params, headers=headers, data=json.dumps(schedule_config)
             )
         )
 
diff --git a/python/hopsworks/job.py b/python/hopsworks/job.py
index 3ce41916b..8e883f366 100644
--- a/python/hopsworks/job.py
+++ b/python/hopsworks/job.py
@@ -194,7 +194,33 @@ def delete(self):
         self._job_api._delete(self)
 
     def schedule(self, cron_expression, start_time=None, end_time=None):
+        """Schedule the execution of the job.
+
+        If a schedule for this job already exists, the method updates it.
+
+        ```python
+        # Schedule the job
+        job.schedule(
+            cron_expression="0 */5 * ? * * *",
+            start_time=datetime.datetime.now(tz=timezone.utc)
+        )
+
+        # Retrieve the next execution time
+        print(job.job_schedule.next_execution_date_time)
+        ```
+
+        # Arguments
+            cron_expression: str. The quartz cron expression
+            start_time: datetime, optional. The schedule start time in UTC.
+                If None, the current time is used. The start_time can be a value in the past.
+            end_time: datetime, optional. The schedule end time in UTC.
+                If None, the schedule will continue running indefinitely.
+                The end_time can be a value in the past.
+        # Returns
+            `JobSchedule`. The schedule of the job
+        """
         job_schedule = js.JobSchedule(
+            id=self._job_schedule.id if self._job_schedule else None,
             start_date_time=start_time if start_time else datetime.now(tz=timezone.utc),
             cron_expression=cron_expression,
             end_time=end_time,
@@ -206,9 +232,9 @@ def schedule(self, cron_expression, start_time=None, end_time=None):
         return self._job_schedule
 
     def unschedule(self):
+        """Unschedule the exceution of a Job"""
         self._job_api._delete_schedule_job(self._name)
         self._job_schedule = None
-        return self._job_schedule
 
     def json(self):
         return json.dumps(self, cls=util.Encoder)