added docstrings to abstract components and card

Author: sQu4rks

webexteamssdk/cards/abstract_components.py

@@ -2,14 +2,43 @@
 import json
 
 class Serializable:
-    """Parent class to
+    """Parent class for all components of adaptive cards.
 
+    Each component should inherit from this class and then specify, from
+    its properties, which fall into the following two categories:
+
+    * Simple properties are text properties like "type" or "id"
+    * Serializable properties are properties that can themselfes be serilized.
+    This includes lists of items (i.e. the 'body' field of the adaptive card) or
+    single objects that also inherit from Serializable
     """
     def __init__(self, serializable_properties, simple_properties):
+        """Creates a serializable object.
+
+        See class docstring for an explanation what the different types of
+        properties are.
+
+        Args:
+            serializable_properties(list): List of all serializable properties
+            simple_properties(list): List of all simple properties.
+        """
         self.serializable_properties = serializable_properties
         self.simple_properties = simple_properties
 
     def to_json(self, pretty=False):
+        """Create json from a serializable component
+
+        This function is used to render the json from a component. While all
+        components do support this operation it is mainly used on the
+        AdaptiveCard to generate the json for the attachment.
+
+        Args:
+            pretty(boolean): If true, the returned json will be sorted by keys
+                and indented with 4 spaces to make it more human-readable
+
+        Returns:
+            A Json representation of this component
+        """
         ret = None
         if pretty:
             ret = json.dumps(self.to_dict(), indent=4, sort_keys=True)
@@ -26,6 +55,10 @@ def to_dict(self):
         (i.e. {'version': "1.2"}) while a serializable property is another
         subcomponent that also implements a to_dict() method.
 
+        The to_dict() method is used to recursively create a dict representation
+        of the adaptive card. This dictionary representation can then be
+        converted into json for usage with the API.
+
         Returns:
             dict: Dictionary representation of this component.
         """
@@ -53,10 +86,3 @@ def to_dict(self):
                 export[cp] = l
 
         return export
-
-class Component:
-    def __init__(self, component_type):
-        self.component_type = component_type
-
-    def get_type(self):
-        return self.component_type

webexteamssdk/cards/card.py

@@ -1,14 +1,39 @@
-from .abstract_components import Serializable, Component
+from .abstract_components import Serializable
 
 class AdaptiveCard(Serializable):
+    """AdaptiveCard class that represents a adaptive card python object.
+
+    Note:
+        Webex Teams currently supports version 1.1 of adaptive cards and thus
+        only features from that release are supported in this abstraction.
+    """
     def __init__(self, body=None,
                        actions=None,
                        selectAction=None,
                        style=None,
                        fallbackText=None,
                        lang=None):
-        super().__init__(serializable_properties=['body', 'actions', 'selectAction', 'style'],
-                         simple_properties=['version', 'fallbackText', 'lang', 'schema', 'type'])
+        """Creates a new adaptive card object.
+
+        Args:
+            body(list): The list of components and containers making up the
+                body of this adaptive card.
+            actions(list): The list of actions this adaptive card should contain
+            selectAction(action): The action that should be invoked when this
+                adaptive card is selected. Can be any action other then
+                'ShowCard'
+            fallbackText(str): The text that should be displayed on clients that
+                can't render adaptive cards
+            lang(str): The 2-letter ISO-639-1 language used in the card. This is
+                used for localization of date/time functions
+
+        """
+        super().__init__(serializable_properties=[
+                            'body', 'actions', 'selectAction', 'style'
+                         ],
+                         simple_properties=[
+                            'version', 'fallbackText', 'lang', 'schema', 'type'
+                         ])
 
         # Set properties
         self.type = "AdaptiveCard"