Fixes part of oppia#4374: Update docstrings in the python backend cod…

…e. (oppia#6028) * Fixes part of oppia#4374 Updated docstrings in Python Backend code for core.storage.base_model.gae_models_test, core.storage.base_model.gae_models, core.storage.user.gae_models, core.tests.test_utils, core.tests.performance_tests.base, core.tests.performance_framework.perf_services, core.tests.performance_framework.perf_domain, core.domain.summary_services, core.domain.email_jobs_one_off_test, core.domain.visualization_registry * Review checks * Review checks oppia#2 * Review checks oppia#3 * Review checks oppia#4 * Review Fixes oppia#5 Minor fix * Review checks oppia#5 Minor fixes * Review checks oppia#5 Minor fixes Merge branch 'docstrings-backend' of https://github.com/YashJipkate/oppia into docstrings-backend * Moved a line up where it can * linting checks linting checks ~2 linting checks ~3 * Added missing args and return docstrings * Address Review * Linting fix Linting fixes * Reviews and linting * Fixed missing params error * Linting checks
quantumferret · Jan 6, 2019 · 25da701 · 25da701
1 parent becb800
commit 25da701
Show file tree

Hide file tree

Showing 10 changed files with 265 additions and 15 deletions.
diff --git a/core/domain/email_jobs_one_off_test.py b/core/domain/email_jobs_one_off_test.py
@@ -45,6 +45,18 @@ def test_hashes_get_generated(self):
         # pylint: disable=unused-argument
         def _generate_hash_for_tests(
                 cls, recipient_id, email_subject, email_body):
+            """Generates hash for tests.
+
+            Args:
+                recipient_id: str. ID of the recipient.
+                email_subject: str. Subject of the email.
+                email_body: str. Body of the email.
+
+            Returns:
+                str. Empty if recipient_id is 'recipient_id2', None if
+                    'recipient_id1' and 'Email Hash' otherwise.
+            """
+
             if recipient_id == 'recipient_id1':
                 return None
             elif recipient_id == 'recipient_id2':

diff --git a/core/domain/summary_services.py b/core/domain/summary_services.py
@@ -493,6 +493,14 @@ def get_library_groups(language_codes):
             '" OR "'.join(language_codes))
 
     def _generate_query(categories):
+        """Generates query based on the categories and language codes.
+
+        Args:
+            categories: list(str). List of categories.
+
+        Returns:
+            str. Generated query.
+        """
         # This assumes that 'categories' is non-empty.
         return 'category=("%s")%s' % (
             '" OR "'.join(categories), language_codes_suffix)

diff --git a/core/domain/visualization_registry.py b/core/domain/visualization_registry.py
@@ -32,6 +32,7 @@ class Registry(object):
 
     @classmethod
     def _refresh_registry(cls):
+        """Clears and adds new visualization instances to the registry."""
         cls.visualizations_dict.clear()
 
         # Add new visualization instances to the registry.

diff --git a/core/storage/base_model/gae_models.py b/core/storage/base_model/gae_models.py
@@ -421,6 +421,7 @@ class VersionedModel(BaseModel):
     version = ndb.IntegerProperty(default=0)
 
     def _require_not_marked_deleted(self):
+        """Checks whether the model instance is deleted."""
         if self.deleted:
             raise Exception('This model instance has been deleted.')
 
@@ -429,6 +430,16 @@ def _compute_snapshot(self):
         return self.to_dict(exclude=['created_on', 'last_updated'])
 
     def _reconstitute(self, snapshot_dict):
+        """Populates the model instance with the snapshot.
+
+        Args:
+            snapshot_dict: dict(str, *). The snapshot with the model
+                property values.
+
+        Returns:
+            VersionedModel. The instance of the VersionedModel class populated
+                with the the snapshot.
+        """
         self.populate(**snapshot_dict)
         return self
 

diff --git a/core/storage/base_model/gae_models_test.py b/core/storage/base_model/gae_models_test.py
@@ -122,10 +122,12 @@ def test_get_new_id_method_does_not_fail_with_bad_names(self):
 
 
 class TestSnapshotMetadataModel(base_models.BaseSnapshotMetadataModel):
+    """Model that inherits the BaseSnapshotMetadataModel for testing."""
     pass
 
 
 class TestSnapshotContentModel(base_models.BaseSnapshotContentModel):
+    """Model that inherits the BaseSnapshotContentModel for testing."""
     pass
 
 
@@ -136,6 +138,7 @@ class TestVersionedModel(base_models.VersionedModel):
 
 
 class TestCommitLogEntryModel(base_models.BaseCommitLogEntryModel):
+    """Model that inherits the BaseCommitLogEntryModel for testing."""
     @classmethod
     def _get_instance_id(cls, target_entity_id, version):
         """A function that returns the id of the log in BaseCommitLogEntryModel.

diff --git a/core/storage/user/gae_models.py b/core/storage/user/gae_models.py
@@ -176,6 +176,17 @@ class ExpUserLastPlaythroughModel(base_models.BaseModel):
 
     @classmethod
     def _generate_id(cls, user_id, exploration_id):
+        """Generates key for the instance of ExpUserLastPlaythroughModel
+        class in the required format with the arguments provided.
+
+        Args:
+            user_id: str. The id of the user.
+            exploration_id: str. The id of the exploration.
+
+        Returns:
+            str. The generated key using user_id and exploration_id
+                of the form [user_id].[exploration_id].
+        """
         return '%s.%s' % (user_id, exploration_id)
 
     @classmethod
@@ -205,7 +216,8 @@ def get(cls, user_id, exploration_id):
 
         Returns:
             ExpUserLastPlaythroughModel. The ExpUserLastPlaythroughModel
-            instance which matches with the given user_id and exploration_id.
+                instance which matches with the given user_id and
+                exploration_id.
         """
         instance_id = cls._generate_id(user_id, exploration_id)
         return super(ExpUserLastPlaythroughModel, cls).get(
@@ -362,7 +374,8 @@ def get_or_create(cls, user_id):
 
         Returns:
             UserStatsModel. Either an existing one which matches the
-            given user_id, or the newly created one if it did not already exist.
+                given user_id, or the newly created one if it did not already
+                exist.
         """
         entity = cls.get(user_id, strict=False)
         if not entity:
@@ -406,6 +419,17 @@ class ExplorationUserDataModel(base_models.BaseModel):
 
     @classmethod
     def _generate_id(cls, user_id, exploration_id):
+        """Generates key for the instance of ExplorationUserDataModel class in
+        the required format with the arguments provided.
+
+        Args:
+            user_id: str. The id of the user.
+            exploration_id: str. The id of the exploration.
+
+        Returns:
+            str. The generated key using user_id and exploration_id
+                of the form [user_id].[exploration_id].
+        """
         return '%s.%s' % (user_id, exploration_id)
 
     @classmethod
@@ -421,7 +445,7 @@ def create(cls, user_id, exploration_id):
 
         Returns:
             ExplorationUserDataModel. The newly created
-            ExplorationUserDataModel instance.
+                ExplorationUserDataModel instance.
         """
         instance_id = cls._generate_id(user_id, exploration_id)
         return cls(
@@ -438,7 +462,7 @@ def get(cls, user_id, exploration_id):
 
         Returns:
             ExplorationUserDataModel. The ExplorationUserDataModel instance
-            which matches with the given user_id and exploration_id.
+                which matches with the given user_id and exploration_id.
         """
         instance_id = cls._generate_id(user_id, exploration_id)
         return super(ExplorationUserDataModel, cls).get(
@@ -455,7 +479,7 @@ def get_multi(cls, user_ids, exploration_id):
 
         Returns:
             ExplorationUserDataModel. The ExplorationUserDataModel instance
-            which matches with the given user_ids and exploration_id.
+                which matches with the given user_ids and exploration_id.
         """
         instance_ids = (
             cls._generate_id(user_id, exploration_id) for user_id in user_ids)
@@ -486,6 +510,17 @@ class CollectionProgressModel(base_models.BaseModel):
 
     @classmethod
     def _generate_id(cls, user_id, collection_id):
+        """Generates key for the instance of CollectionProgressModel class in
+        the required format with the arguments provided.
+
+        Args:
+            user_id: str. The id of the user.
+            collection_id: str. The id of the exploration.
+
+        Returns:
+            str. The generated key using user_id and exploration_id
+                of the form [user_id].[collection_id].
+        """
         return '%s.%s' % (user_id, collection_id)
 
     @classmethod
@@ -501,7 +536,7 @@ def create(cls, user_id, collection_id):
 
         Returns:
             CollectionProgressModel. The newly created CollectionProgressModel
-            instance.
+                instance.
         """
         instance_id = cls._generate_id(user_id, collection_id)
         return cls(
@@ -518,7 +553,7 @@ def get(cls, user_id, collection_id):
 
         Returns:
             CollectionProgressModel. The CollectionProgressModel instance which
-            matches the given user_id and collection_id.
+                matches the given user_id and collection_id.
         """
         instance_id = cls._generate_id(user_id, collection_id)
         return super(CollectionProgressModel, cls).get(
@@ -555,8 +590,8 @@ def get_or_create(cls, user_id, collection_id):
 
         Returns:
             CollectionProgressModel. Either an existing one which
-            matches the given user_id and collection_id, or the newly created
-            one if it does not already exist.
+                matches the given user_id and collection_id, or the newly
+                created one if it does not already exist.
         """
         instance_model = cls.get(user_id, collection_id)
         if instance_model:
@@ -608,7 +643,7 @@ def create(cls, user_id, story_id):
 
         Returns:
             StoryProgressModel. The newly created StoryProgressModel
-            instance.
+                instance.
         """
         instance_id = cls._generate_id(user_id, story_id)
         return cls(
@@ -627,7 +662,7 @@ def get(cls, user_id, story_id, strict=True):
 
         Returns:
             StoryProgressModel. The StoryProgressModel instance which
-            matches the given user_id and story_id.
+                matches the given user_id and story_id.
         """
         instance_id = cls._generate_id(user_id, story_id)
         return super(StoryProgressModel, cls).get(
@@ -644,7 +679,7 @@ def get_multi(cls, user_id, story_ids):
 
         Returns:
             list(StoryProgressModel). The list of StoryProgressModel
-            instances which matches the given user_id and story_ids.
+                instances which matches the given user_id and story_ids.
         """
         instance_ids = [cls._generate_id(user_id, story_id)
                         for story_id in story_ids]
@@ -667,8 +702,8 @@ def get_or_create(cls, user_id, story_id):
 
         Returns:
             StoryProgressModel. Either an existing one which
-            matches the given user_id and story_id, or the newly created
-            one if it does not already exist.
+                matches the given user_id and story_id, or the newly created
+                one if it does not already exist.
         """
         instance_model = cls.get(user_id, story_id, strict=False)
         if instance_model is not None:

diff --git a/core/tests/performance_framework/perf_domain.py b/core/tests/performance_framework/perf_domain.py
@@ -173,6 +173,18 @@ def get_total_page_size_bytes(self):
         return total_size
 
     def _get_duration_millisecs(self, event_end, event_initial):
+        """Get page load duration.
+
+        Args:
+            event_end: str. The event up to which duration measurement is
+                required.
+            event_initial: str. The event from which duration measurement
+                starts.
+
+        Returns:
+            int. The calculated time duration between event_initial and
+                event_end in milliseconds.
+        """
         # Timestamps are in milliseconds.
         initial_timestamp = self.page_load_timings[event_initial]
         end_timestamp = self.page_load_timings[event_end]
@@ -272,6 +284,7 @@ def __init__(self, page_session_metrics):
         self._validate()
 
     def _validate(self):
+        """Checks whether the page metrics are in the list format."""
         if not isinstance(self.page_metrics, list):
             raise utils.ValidationError(
                 'Expected page_session_metrics to be a list, '