From 6bd0e7dc3a3aeb148fab5b90fa333e2a47ed049c Mon Sep 17 00:00:00 2001
From: Mike Salvatore <mike.s.salvatore@gmail.com>
Date: Thu, 7 Jul 2022 15:08:17 -0400
Subject: [PATCH] Common: Add doctrings for Credential serialization

---
 monkey/common/credentials/credentials.py | 50 ++++++++++++++++++++++--
 1 file changed, 46 insertions(+), 4 deletions(-)

diff --git a/monkey/common/credentials/credentials.py b/monkey/common/credentials/credentials.py
index 291d488ca..34ee346fb 100644
--- a/monkey/common/credentials/credentials.py
+++ b/monkey/common/credentials/credentials.py
@@ -122,6 +122,17 @@ class Credentials:
 
     @staticmethod
     def from_mapping(credentials: Mapping) -> Credentials:
+        """
+        Construct a Credentials object from a Mapping
+
+        :param credentials: A mapping that represents a Credentials object
+        :return: A Credentials object
+        :raises InvalidCredentialsError: If the provided Mapping does not represent a valid
+                                         Credentials object
+        :raises InvalidCredentialComponentError: If any of the contents of `identities` or `secrets`
+                                                 are not a valid ICredentialComponent
+        """
+
         try:
             deserialized_data = CredentialsSchema().load(credentials)
             return Credentials(**deserialized_data)
@@ -132,6 +143,17 @@ class Credentials:
 
     @staticmethod
     def from_json(credentials: str) -> Credentials:
+        """
+        Construct a Credentials object from a JSON string
+
+        :param credentials: A JSON string that represents a Credentials object
+        :return: A Credentials object
+        :raises InvalidCredentialsError: If the provided JSON does not represent a valid
+                                         Credentials object
+        :raises InvalidCredentialComponentError: If any of the contents of `identities` or `secrets`
+                                                 are not a valid ICredentialComponent
+        """
+
         try:
             deserialized_data = CredentialsSchema().loads(credentials)
             return Credentials(**deserialized_data)
@@ -140,11 +162,31 @@ class Credentials:
         except MarshmallowError as err:
             raise InvalidCredentialsError(str(err))
 
-    @staticmethod
-    def to_json(credentials: Credentials) -> str:
-        return CredentialsSchema().dumps(credentials)
-
     @staticmethod
     def from_json_array(credentials_array_json: str) -> Sequence[Credentials]:
+        """
+        Construct a sequence of Credentials object from a JSON string
+
+        :param credentials: A JSON string that represents an array of Credentials objects
+        :return: A Sequence of Credentials objects
+        :raises InvalidCredentialsError: If the provided JSON does not represent a valid
+                                         Credentials object
+        :raises InvalidCredentialComponentError: If any of the contents of `identities` or `secrets`
+                                                 are not a valid ICredentialComponent
+        :raises JSONDecodeError: If the provided string is not valid JSON
+        :raises TypeError: If the provided JSON does not represent an array
+        """
+
         credentials_list = json.loads(credentials_array_json)
         return [Credentials.from_mapping(c) for c in credentials_list]
+
+    @staticmethod
+    def to_json(credentials: Credentials) -> str:
+        """
+        Serialize a Credentials object to JSON
+
+        :param credentials: A Credentials objcet
+        :return: A JSON string representing a Credentials object
+        """
+
+        return CredentialsSchema().dumps(credentials)