Fix part of oppia#4374: Add docstrings to Python files. (oppia#6013)

* Add docstrings. * Made review changes. * Resolve lint errors. * Made requested changes.
quantumferret · Dec 25, 2018 · 92c4ecf · 92c4ecf
1 parent a0e721c
commit 92c4ecf
Show file tree

Hide file tree

Showing 16 changed files with 207 additions and 11 deletions.
diff --git a/core/domain/classifier_domain_test.py b/core/domain/classifier_domain_test.py
@@ -27,6 +27,9 @@ class ClassifierTrainingJobDomainTests(test_utils.GenericTestBase):
     """Test the ClassifierTrainingJob domain."""
 
     def _get_training_job_from_dict(self, training_job_dict):
+        """Returns the ClassifierTrainingJob object after receiving the content
+        from the training_job_dict.
+        """
         training_job = classifier_domain.ClassifierTrainingJob(
             training_job_dict['job_id'],
             training_job_dict['algorithm_id'],
@@ -163,6 +166,9 @@ class TrainingJobExplorationMappingDomainTests(test_utils.GenericTestBase):
     """Tests for the TrainingJobExplorationMapping domain."""
 
     def _get_mapping_from_dict(self, mapping_dict):
+        """Returns the TrainingJobExplorationMapping object after receiving the
+        content from the mapping_dict.
+        """
         mapping = classifier_domain.TrainingJobExplorationMapping(
             mapping_dict['exp_id'],
             mapping_dict['exp_version'],

diff --git a/core/domain/email_manager.py b/core/domain/email_manager.py
@@ -265,6 +265,7 @@ def _send_email(
         return
 
     def _send_email_in_transaction():
+        """Sends the email to a single recipient."""
         sender_name_email = '%s <%s>' % (sender_name, sender_email)
 
         email_services.send_mail(
@@ -312,6 +313,7 @@ def _send_bulk_mail(
     cleaned_plaintext_body = html_cleaner.strip_html_tags(raw_plaintext_body)
 
     def _send_bulk_mail_in_transaction(instance_id=None):
+        """Sends the emails in bulk to the recipients."""
         sender_name_email = '%s <%s>' % (sender_name, sender_email)
 
         email_services.send_bulk_mail(

diff --git a/core/domain/email_manager_test.py b/core/domain/email_manager_test.py
@@ -535,6 +535,7 @@ def test_email_not_sent_if_content_config_is_not_modified(self):
         logged_errors = []
 
         def _log_error_for_tests(error_message):
+            """Appends the error message to the logged errors list."""
             logged_errors.append(error_message)
 
         log_new_error_counter = test_utils.CallCounter(_log_error_for_tests)
@@ -582,6 +583,7 @@ def test_email_not_sent_if_content_config_is_partially_modified(self):
         logged_errors = []
 
         def _log_error_for_tests(error_message):
+            """Appends the error message to the logged errors list."""
             logged_errors.append(error_message)
 
         log_new_error_counter = test_utils.CallCounter(_log_error_for_tests)
@@ -627,6 +629,7 @@ def test_email_with_bad_content_is_not_sent(self):
         logged_errors = []
 
         def _log_error_for_tests(error_message):
+            """Appends the error message to the logged errors list."""
             logged_errors.append(error_message)
 
         log_new_error_counter = test_utils.CallCounter(_log_error_for_tests)
@@ -845,6 +848,7 @@ def setUp(self):
         def _generate_hash_for_tests(
                 unused_cls, unused_recipient_id, unused_email_subject,
                 unused_email_body):
+            """Returns the generated hash for tests."""
             return 'Email Hash'
 
         self.generate_hash_ctx = self.swap(
@@ -863,6 +867,7 @@ def test_send_email_does_not_resend_if_same_hash_exists(self):
         logged_errors = []
 
         def _log_error_for_tests(error_message):
+            """Appends the error message to the logged errors list."""
             logged_errors.append(error_message)
 
         log_new_error_counter = test_utils.CallCounter(_log_error_for_tests)
@@ -914,6 +919,7 @@ def test_send_email_does_not_resend_within_duplicate_interval(self):
         logged_errors = []
 
         def _log_error_for_tests(error_message):
+            """Appends the error message to the logged errors list."""
             logged_errors.append(error_message)
 
         log_new_error_counter = test_utils.CallCounter(_log_error_for_tests)

diff --git a/core/domain/feedback_jobs_continuous_test.py b/core/domain/feedback_jobs_continuous_test.py
@@ -58,11 +58,15 @@ class FeedbackAnalyticsAggregatorUnitTests(test_utils.GenericTestBase):
     ALL_CC_MANAGERS_FOR_TESTS = [MockFeedbackAnalyticsAggregator]
 
     def _get_swap_context(self):
+        """Substitutes the jobs_registry.ALL_CONTINUOUS_COMPUTATION_MANAGERS
+        value with ALL_CC_MANAGERS_FOR_TESTS.
+        """
         return self.swap(
             jobs_registry, 'ALL_CONTINUOUS_COMPUTATION_MANAGERS',
             self.ALL_CC_MANAGERS_FOR_TESTS)
 
     def _run_job(self):
+        """Runs the job, then processes and flushes all the pending tasks."""
         self.process_and_flush_pending_tasks()
         MockFeedbackAnalyticsAggregator.start_computation()
         self.assertEqual(
@@ -72,6 +76,7 @@ def _run_job(self):
 
     def _run_job_and_check_results(
             self, exp_id, expected_thread_analytics_dict):
+        """Runs the job and checks the thread analytics dict."""
         self._run_job()
         self.assertEqual(
             MockFeedbackAnalyticsAggregator.get_thread_analytics(
@@ -436,12 +441,18 @@ class RealtimeFeedbackAnalyticsUnitTests(test_utils.GenericTestBase):
     ALL_CC_MANAGERS_FOR_TESTS = [MockFeedbackAnalyticsAggregator]
 
     def _get_swap_context(self):
+        """Substitutes the jobs_registry.ALL_CONTINUOUS_COMPUTATION_MANAGERS
+        value with ALL_CC_MANAGERS_FOR_TESTS.
+        """
         return self.swap(
             jobs_registry, 'ALL_CONTINUOUS_COMPUTATION_MANAGERS',
             self.ALL_CC_MANAGERS_FOR_TESTS)
 
     def _flush_tasks_and_check_analytics(
             self, exp_id, expected_thread_analytics_dict):
+        """Processes and flushes the pending tasks, then checks the thread
+        analytics dict.
+        """
         self.process_and_flush_pending_tasks()
         self.assertEqual(
             MockFeedbackAnalyticsAggregator.get_thread_analytics(

diff --git a/core/domain/learner_playlist_services_test.py b/core/domain/learner_playlist_services_test.py
@@ -79,6 +79,9 @@ def setUp(self):
             category='Welcome')
 
     def _get_all_learner_playlist_exp_ids(self, user_id):
+        """Returns the list of all the exploration ids in the learner's playlist
+        corresponding to the given user id.
+        """
         learner_playlist_model = user_models.LearnerPlaylistModel.get(
             user_id, strict=False)
 
@@ -87,6 +90,9 @@ def _get_all_learner_playlist_exp_ids(self, user_id):
             learner_playlist_model else [])
 
     def _get_all_learner_playlist_collection_ids(self, user_id):
+        """Returns the list of all the collection ids in the learner's playlist
+        corresponding to the given user id.
+        """
         learner_playlist_model = user_models.LearnerPlaylistModel.get(
             user_id, strict=False)
 

diff --git a/core/domain/learner_progress_services_test.py b/core/domain/learner_progress_services_test.py
@@ -88,6 +88,9 @@ def setUp(self):
         self.publish_collection(self.owner_id, self.COL_ID_3)
 
     def _get_all_completed_exp_ids(self, user_id):
+        """Gets the ids of all the explorations completed by the learner
+        corresponding to the given user id.
+        """
         completed_activities_model = (
             user_models.CompletedActivitiesModel.get(
                 user_id, strict=False))
@@ -97,6 +100,9 @@ def _get_all_completed_exp_ids(self, user_id):
             completed_activities_model else [])
 
     def _get_all_completed_collection_ids(self, user_id):
+        """Gets the ids of all the collections completed by the learner
+        corresponding to the given user id.
+        """
         completed_activities_model = (
             user_models.CompletedActivitiesModel.get(
                 user_id, strict=False))
@@ -106,6 +112,9 @@ def _get_all_completed_collection_ids(self, user_id):
             completed_activities_model else [])
 
     def _get_all_incomplete_exp_ids(self, user_id):
+        """Gets the ids of all the explorations not fully completed by the
+        learner corresponding to the given user id.
+        """
         incomplete_activities_model = (
             user_models.IncompleteActivitiesModel.get(user_id, strict=False))
 
@@ -114,6 +123,9 @@ def _get_all_incomplete_exp_ids(self, user_id):
             incomplete_activities_model else [])
 
     def _get_incomplete_exp_details(self, user_id, exploration_id):
+        """Returns the dict containing all the exploration details that are
+        incompletely played by the learner corresponding to the given user id.
+        """
         incomplete_exploration_user_model = (
             user_models.ExpUserLastPlaythroughModel.get(
                 user_id, exploration_id))
@@ -128,6 +140,9 @@ def _get_incomplete_exp_details(self, user_id, exploration_id):
 
     def _check_if_exp_details_match(
             self, actual_details, details_fetched_from_model):
+        """Verifies the exploration details fetched from the model matches the
+        actual details.
+        """
         self.assertEqual(
             actual_details['state_name'],
             details_fetched_from_model['state_name'])
@@ -143,6 +158,9 @@ def _check_if_exp_details_match(
             details_fetched_from_model['timestamp']).total_seconds(), 10)
 
     def _get_all_incomplete_collection_ids(self, user_id):
+        """Returns the list of all the collection ids that are incompletely
+        played by the learner corresponding to the given user id.
+        """
         incomplete_activities_model = (
             user_models.IncompleteActivitiesModel.get(user_id, strict=False))
 

diff --git a/core/domain/obj_services.py b/core/domain/obj_services.py
@@ -31,6 +31,9 @@ class Registry(object):
 
     @classmethod
     def _refresh_registry(cls):
+        """Refreshes the registry by adding new object instances to the
+        registry.
+        """
         cls.objects_dict.clear()
 
         # Add new object instances to the registry.

diff --git a/core/domain/rating_services.py b/core/domain/rating_services.py
@@ -57,6 +57,9 @@ def assign_rating_to_exploration(user_id, exploration_id, new_rating):
         raise Exception('Invalid exploration id %s' % exploration_id)
 
     def _update_user_rating():
+        """Updates the user rating of the exploration. Returns the old rating
+        before updation.
+        """
         exp_user_data_model = user_models.ExplorationUserDataModel.get(
             user_id, exploration_id)
         if exp_user_data_model:

diff --git a/core/domain/stats_jobs_continuous_test.py b/core/domain/stats_jobs_continuous_test.py
@@ -66,13 +66,19 @@ class InteractionAnswerSummariesAggregatorTests(test_utils.GenericTestBase):
     ALL_CC_MANAGERS_FOR_TESTS = [MockInteractionAnswerSummariesAggregator]
 
     def _record_start(self, exp_id, exp_version, state_name, session_id):
+        """Calls StartExplorationEventHandler and starts recording the
+        exploration events corresponding to the given exploration id.
+        """
         event_services.StartExplorationEventHandler.record(
             exp_id, exp_version, state_name, session_id, {},
             feconf.PLAY_TYPE_NORMAL)
 
     def _get_calc_output_model(
             self, exploration_id, state_name, calculation_id,
             exploration_version=stats_jobs_continuous.VERSION_ALL):
+        """Gets the StateAnswersCalcOutputModel corresponding to the given
+        calculation_id.
+        """
         return stats_models.StateAnswersCalcOutputModel.get_model(
             exploration_id, exploration_version, state_name, calculation_id)
 

diff --git a/core/domain/stats_services_test.py b/core/domain/stats_services_test.py
@@ -1569,26 +1569,36 @@ class AnswerVisualizationsTests(test_utils.GenericTestBase):
     NEW_STATE_NAME = 'new state'
 
     def _get_swap_context(self):
+        """Substitutes the jobs_registry.ALL_CONTINUOUS_COMPUTATION_MANAGERS
+        value with ALL_CC_MANAGERS_FOR_TESTS.
+        """
         return self.swap(
             jobs_registry, 'ALL_CONTINUOUS_COMPUTATION_MANAGERS',
             self.ALL_CC_MANAGERS_FOR_TESTS)
 
     def _get_visualizations(
             self, exp_id=TEXT_INPUT_EXP_ID, state_name=INIT_STATE_NAME):
+        """Returns the visualizations info corresponding to the given
+        exploration id and state name.
+        """
         exploration = exp_services.get_exploration_by_id(exp_id)
         init_state = exploration.states[state_name]
         return stats_services.get_visualizations_info(
             exp_id, state_name, init_state.interaction.id)
 
     def _record_answer(
             self, answer, exp_id=TEXT_INPUT_EXP_ID, state_name=INIT_STATE_NAME):
+        """Records the submitted answer corresponding to the given exploration
+        id and state name.
+        """
         exploration = exp_services.get_exploration_by_id(exp_id)
         interaction_id = exploration.states[state_name].interaction.id
         event_services.AnswerSubmissionEventHandler.record(
             exp_id, exploration.version, state_name, interaction_id, 0, 0,
             exp_domain.EXPLICIT_CLASSIFICATION, 'sid1', 10.0, {}, answer)
 
     def _run_answer_summaries_aggregator(self):
+        """Runs the MockInteractionAnswerSummariesAggregator."""
         MockInteractionAnswerSummariesAggregator.start_computation()
         self.assertEqual(
             self.count_jobs_in_taskqueue(
@@ -1599,12 +1609,16 @@ def _run_answer_summaries_aggregator(self):
                 taskqueue_services.QUEUE_NAME_CONTINUOUS_JOBS), 0)
 
     def _rerun_answer_summaries_aggregator(self):
+        """Reruns the MockInteractionAnswerSummariesAggregator."""
         MockInteractionAnswerSummariesAggregator.stop_computation('a')
         self._run_answer_summaries_aggregator()
 
     def _rename_state(
             self, new_state_name, exp_id=TEXT_INPUT_EXP_ID,
             state_name=INIT_STATE_NAME):
+        """Renames the state corresponding to the given exploration id
+        and state name.
+        """
         exp_services.update_exploration(
             self.owner_id, exp_id, [exp_domain.ExplorationChange({
                 'cmd': exp_domain.CMD_RENAME_STATE,
@@ -1615,6 +1629,9 @@ def _rename_state(
     def _change_state_interaction_id(
             self, interaction_id, exp_id=TEXT_INPUT_EXP_ID,
             state_name=INIT_STATE_NAME):
+        """Updates the state interaction id corresponding to the given
+        exploration id and state name.
+        """
         exp_services.update_exploration(
             self.owner_id, exp_id, [exp_domain.ExplorationChange({
                 'cmd': exp_domain.CMD_EDIT_STATE_PROPERTY,
@@ -1626,6 +1643,9 @@ def _change_state_interaction_id(
     def _change_state_content(
             self, new_content, exp_id=TEXT_INPUT_EXP_ID,
             state_name=INIT_STATE_NAME):
+        """Updates the state content corresponding to the given exploration id
+        and state name.
+        """
         exp_services.update_exploration(
             self.owner_id, exp_id, [exp_domain.ExplorationChange({
                 'cmd': exp_domain.CMD_EDIT_STATE_PROPERTY,
@@ -1894,15 +1914,24 @@ class StateAnswersStatisticsTest(test_utils.GenericTestBase):
 
     def _get_top_state_answer_stats(
             self, exp_id=EXP_ID, state_name=STATE_NAMES[0]):
+        """Returns the top answer stats corresponding to the given exploration
+        id and state names.
+        """
         return stats_services.get_top_state_answer_stats(exp_id, state_name)
 
     def _get_top_state_unresolved_answer_stats(
             self, exp_id=EXP_ID, state_name=STATE_NAMES[0]):
+        """Returns the top unresolved answer stats corresponding to the given
+        exploration id and state names.
+        """
         return stats_services.get_top_state_unresolved_answers(
             exp_id, state_name)
 
     def _get_top_state_answer_stats_multi(
             self, exp_id=EXP_ID, state_names=None):
+        """Returns the top answer stats corresponding to the given exploration
+        id and state names.
+        """
         if not state_names:
             raise ValueError('Must provide non-empty state names.')
         return stats_services.get_top_state_answer_stats_multi(
@@ -1911,13 +1940,17 @@ def _get_top_state_answer_stats_multi(
     def _record_answer(
             self, answer, exp_id=EXP_ID, state_name=STATE_NAMES[0],
             classification_category=exp_domain.EXPLICIT_CLASSIFICATION):
+        """Records the submitted answer corresponding to the given interaction
+        id in an exploration.
+        """
         exploration = exp_services.get_exploration_by_id(exp_id)
         interaction_id = exploration.states[state_name].interaction.id
         event_services.AnswerSubmissionEventHandler.record(
             exp_id, exploration.version, state_name, interaction_id, 0, 0,
             classification_category, 'sid1', 10.0, {}, answer)
 
     def _run_answer_summaries_aggregator(self):
+        """Runs the MockInteractionAnswerSummariesAggregator."""
         MockInteractionAnswerSummariesAggregator.start_computation()
         self.assertEqual(
             self.count_jobs_in_taskqueue(

diff --git a/core/domain/story_services_test.py b/core/domain/story_services_test.py
@@ -424,10 +424,14 @@ class StoryProgressUnitTests(StoryServicesUnitTests):
     """
 
     def _get_progress_model(self, user_id, STORY_ID):
+        """Returns the StoryProgressModel corresponding to the story id and user
+        id.
+        """
         return user_models.StoryProgressModel.get(
             user_id, STORY_ID, strict=False)
 
     def _record_completion(self, user_id, STORY_ID, node_id):
+        """Records the completion of a node in the context of a story."""
         story_services.record_completed_node_in_story_context(
             user_id, STORY_ID, node_id)