Fix part of oppia#4374: Updated Docstrings in Python Backend Code of …

…core.jobs (oppia#5977) * Fixes oppia#4374 Updated Docstrings in Python Backend Code of core.jobs * Fixes oppia#4374 Updated Docstrings in Python Backend Code of core.jobs * Fixes oppia#4374 Updated Docstrings in Python Backend Code of core.jobs
quantumferret · Dec 15, 2018 · e7044ef · e7044ef
1 parent b1570e2
commit e7044ef
Showing 1 changed file with 101 additions and 0 deletions.
diff --git a/core/jobs.py b/core/jobs.py
@@ -101,6 +101,11 @@ class BaseJobManager(object):
     """
     @classmethod
     def _is_abstract(cls):
+        """Checks if the job is created using the abstract base manager class.
+
+        Returns:
+            bool. Whether the job is created using abstract base manager class.
+        """
         return cls in ABSTRACT_BASE_CLASSES
 
     @classmethod
@@ -120,6 +125,12 @@ def create_new(cls):
                 'manager class %s, which is not allowed.' % cls.__name__)
 
         def _create_new_job():
+            """Creates a new job by generating a unique id and inserting
+            it into the model.
+
+            Returns:
+                str. The unique job id.
+            """
             job_id = job_models.JobModel.get_new_id(cls.__name__)
             job_models.JobModel(id=job_id, job_type=cls.__name__).put()
             return job_id
@@ -484,34 +495,83 @@ def _require_correct_job_type(cls, job_type):
 
     @classmethod
     def _pre_enqueue_hook(cls, job_id):
+        """A hook or a callback function triggered before enqueuing a job.
+
+        Args:
+            job_id: str. The unique ID of the job which is to be enqueued.
+        """
         pass
 
     @classmethod
     def _post_enqueue_hook(cls, job_id):
+        """A hook or a callback function triggered after enqueuing a job.
+
+        Args:
+            job_id: str. The unique ID of the job which was enqueued.
+        """
         pass
 
     @classmethod
     def _pre_start_hook(cls, job_id):
+        """A hook or a callback function triggered before marking a job
+        as started.
+
+        Args:
+            job_id: str. The unique ID of the job to be marked as started.
+        """
         pass
 
     @classmethod
     def _post_start_hook(cls, job_id):
+        """A hook or a callback function triggered after marking a job as
+        started.
+
+        Args:
+            job_id: str. The unique ID of the job marked as started.
+        """
         pass
 
     @classmethod
     def _post_completed_hook(cls, job_id):
+        """A hook or a callback function triggered after marking a job as
+        completed.
+
+        Args:
+            job_id: str. The unique ID of the job marked as completed.
+        """
         pass
 
     @classmethod
     def _post_failure_hook(cls, job_id):
+        """A hook or a callback function triggered after marking a job as
+        failed.
+
+        Args:
+            job_id: str. The unique ID of the job marked as failed.
+        """
         pass
 
     @classmethod
     def _pre_cancel_hook(cls, job_id, cancel_message):
+        """A hook or a callback function triggered before marking a job as
+        cancelled.
+
+        Args:
+            job_id: str. The unique ID of the job to be marked as cancelled.
+            cancel_message: str. The message to be displayed before
+                cancellation.
+        """
         pass
 
     @classmethod
     def _post_cancel_hook(cls, job_id, cancel_message):
+        """A hook or a callback function triggered after marking a job as
+        cancelled.
+
+        Args:
+            job_id: str. The unique ID of the job marked as cancelled.
+            cancel_message: str. The message to be displayed after cancellation.
+        """
         pass
 
 
@@ -814,6 +874,14 @@ def _real_enqueue(cls, job_id, queue_name, additional_job_params):
 
     @classmethod
     def _pre_cancel_hook(cls, job_id, cancel_message):
+        """A hook or a callback function triggered before marking a job as
+        cancelled.
+
+        Args:
+            job_id: str. The unique ID of the job to be marked as cancelled.
+            cancel_message: str. The message to be displayed before
+                cancellation.
+        """
         metadata = cls.get_metadata(job_id)
         root_pipeline_id = metadata[cls._OUTPUT_KEY_ROOT_PIPELINE_ID]
         pipeline.Pipeline.from_id(root_pipeline_id).abort(cancel_message)
@@ -1000,14 +1068,33 @@ def _entity_created_before_job_queued(entity):
 
     @classmethod
     def _post_completed_hook(cls, job_id):
+        """A hook or a callback function triggered after marking a job as
+        completed.
+
+        Args:
+            job_id: str. The unique ID of the job marked as completed.
+        """
         cls._get_continuous_computation_class().on_batch_job_completion()
 
     @classmethod
     def _post_cancel_hook(cls, job_id, cancel_message):
+        """A hook or a callback function triggered after marking a job as
+        cancelled.
+
+        Args:
+            job_id: str. The unique ID of the job marked as cancelled.
+            cancel_message: str. The message to be displayed after cancellation.
+        """
         cls._get_continuous_computation_class().on_batch_job_canceled()
 
     @classmethod
     def _post_failure_hook(cls, job_id):
+        """A hook or a callback function triggered after marking a job as
+        failed.
+
+        Args:
+            job_id: str. The unique ID of the job marked as failed.
+        """
         cls._get_continuous_computation_class().on_batch_job_failure()
 
 
@@ -1237,6 +1324,13 @@ def _get_active_realtime_index(cls):
             str. The active realtime layer index of this class.
         """
         def _get_active_realtime_index_transactional():
+            """Finds the Continous Computation Model corresponding to this
+            class type or inserts it in the database if not found and extracts
+            the active realtime layer index.
+
+            Returns:
+                str. The active realtime layer index of this class.
+            """
             cc_model = job_models.ContinuousComputationModel.get(
                 cls.__name__, strict=False)
             if cc_model is None:
@@ -1289,6 +1383,9 @@ def _switch_active_realtime_class(cls):
         computation.
         """
         def _switch_active_realtime_class_transactional():
+            """Retrieves currently-active realtime layer index, switches it
+            and inserts the new model to the database.
+            """
             cc_model = job_models.ContinuousComputationModel.get(
                 cls.__name__)
             cc_model.active_realtime_layer_index = (
@@ -1469,6 +1566,10 @@ def _process_job_completion_and_return_status(cls):
         cls._clear_inactive_realtime_layer(datetime.datetime.utcnow())
 
         def _update_last_finished_time_transactional():
+            """Updates the time at which a batch job for this computation was
+            last completed or failed, in milliseconds since the epoch, setting
+            it to the current time.
+            """
             cc_model = job_models.ContinuousComputationModel.get(cls.__name__)
             cc_model.last_finished_msec = utils.get_current_time_in_millisecs()
             cc_model.put()