Merge pull request #9 from SlicingDice/feature/add-code-comments

Add comments to code

Author: joaosimbiose

pyslicer/api.py

@@ -25,10 +25,10 @@ def __init__(
 
         Keyword arguments:
         key(string or SlicerKey) -- Key(s) to access API
-        timeout(int) -- Define timeout to request,
-            defaults 30 secs(Optional).
         use_ssl(bool) -- Define if the request uses verification SSL for
             HTTPS requests. Defaults False.(Optional)
+        timeout(int) -- Define timeout to request,
+            defaults 30 secs(Optional).
         """
         self.keys = self._organize_keys(
             master_key, custom_key, read_key, write_key)
@@ -69,8 +69,7 @@ def _check_key(self, key_level):
         """Select automatically a key to make the request in Slicing Dice
 
         Keyword arguments:
-        need_write(bool) -- Define if this request needs write in Slicing
-            Dice API.
+        key_level(int) -- Define the key level needed
         """
         current_key_level = self._get_key()
         if current_key_level[1] == 2:
@@ -81,7 +80,14 @@ def _check_key(self, key_level):
         return current_key_level[0]
 
     def _make_request(self, url, req_type, key_level, json_data=None):
-        """Returns a object request result"""
+        """Returns a object request result
+
+        Keyword arguments:
+        url(string) -- the url to make a request
+        req_type(string) -- the request type (POST, PUT, DELETE or GET)
+        key_level(int) -- Define the key level needed
+        json_data(json) -- The json to use on request (default None)
+        """
         self._check_key(key_level)
         headers = {'Content-Type': 'application/json',
                    'Authorization': self._api_key}
@@ -112,7 +118,11 @@ def _make_request(self, url, req_type, key_level, json_data=None):
         return self._handler_request(req)
 
     def _handler_request(self, req):
-        """Handler request response"""
+        """Handler request response
+
+        Keyword arguments:
+        req -- the request object
+        """
         if req is None:
             raise exceptions.SlicingDiceException("Bad request.")
 

pyslicer/client.py

@@ -32,21 +32,21 @@ class SlicingDice(SlicingDiceAPI):
 
         To create an object of the SliceDicer:
 
-            >>> from pyslicer.api import SlicingDice
-            >>> sd = SlicingDice('my-token')
+            from pyslicer.api import SlicingDice
+            sd = SlicingDice('my-token')
 
         To create a field:
 
-            >>> field_json = {
+                field_json = {
                     'name': 'Pyslicer String Field',
                     'description': 'Pyslicer example description',
                     'type': 'string',
                     'cardinality': 'low'}
-            >>> print sd.create_field(field_json)
+                print sd.create_field(field_json)
 
         To make a query:
 
-            >>> query_json = {
+                query_json = {
                     'type': 'count',
                     'select': [
                         {
@@ -64,11 +64,11 @@ class SlicingDice(SlicingDiceAPI):
                         },
                     ]
                 }
-            >>> print sd.query(query_json)
+                print sd.query(query_json)
 
         To make a index:
 
-            >>> indexing_json = {
+                indexing_json = {
                     'foo@bar.com': {
                         'pyslicer-string-field': 'test_value_1',
                         'pyslicer-integer-field': 42,
@@ -78,7 +78,7 @@ class SlicingDice(SlicingDiceAPI):
                         'pyslicer-integer-field': 42,
                     },
                 }
-            >>> print sd.index(indexing_json)
+                print sd.index(indexing_json)
     """
     def __init__(
         self, write_key=None, read_key=None, master_key=None,
@@ -87,10 +87,10 @@ def __init__(
 
         Keyword arguments:
         key(string or SlicerKey obj) -- Key to access API
-        timeout(int) -- Define timeout to request,
-            defaults 30 secs(default 30).
         use_ssl(bool) -- Define if the request uses verification SSL for
             HTTPS requests. Defaults False.(Optional)
+        timeout(int) -- Define timeout to request,
+            defaults 30 secs(default 30).
         """
         super(SlicingDice, self).__init__(
             write_key, read_key, master_key, custom_key, use_ssl, timeout)
@@ -141,20 +141,17 @@ def _saved_query_wrapper(self, url, query, update=False):
         update(bool) -- Indicates with operation is update a
             saved query or not.(default false)
         """
+        req_type = "post"
         if update:
-            return self._make_request(
-                url=url,
-                json_data=ujson.dumps(query),
-                req_type="put",
-                key_level=2)
+            req_type = "put"
         return self._make_request(
             url=url,
             json_data=ujson.dumps(query),
-            req_type="post",
+            req_type=req_type,
             key_level=2)
 
     def get_projects(self):
-        """Get a list of projects"""
+        """Get a list of projects (all)"""
         url = SlicingDice.BASE_URL + URLResources.PROJECT
         return self._make_request(
             url=url,
@@ -168,6 +165,7 @@ def create_field(self, data, test=False):
         Keyword arguments:
         data -- A dictionary in the Slicing Dice field
             format.
+        test(bool) -- if true will use tests end-point (default False)
         """
         base_url = self._wrapper_test(test)
         sd_data = validators.FieldValidator(data)
@@ -180,7 +178,11 @@ def create_field(self, data, test=False):
                 key_level=1)
 
     def get_fields(self, test=False):
-        """Get a list of fields"""
+        """Get a list of fields
+
+        Keyword arguments:
+        test(bool) -- if true will use tests end-point (default False)
+        """
         base_url = self._wrapper_test(test)
         url = base_url + URLResources.FIELD
         return self._make_request(
@@ -189,11 +191,14 @@ def get_fields(self, test=False):
             key_level=2)
 
     def index(self, data, auto_create_fields=False, test=False):
-        """Make a index in Slicing Dice
+        """Make a index in Slicing Dice API
 
         Keyword arguments:
         data -- A dictionary in the Slicing Dice index
             format.
+        auto_create_fields(bool) -- if true SlicingDice API will automatically
+            create nonexistent fields (default False)
+        test(bool) -- if true will use tests end-point (default False)
         """
         if auto_create_fields:
             data["auto-create-fields"] = True
@@ -212,13 +217,17 @@ def count_entity(self, query, test=False):
 
         Keyword arguments:
         query -- A dictionary in the Slicing Dice query
+        test(bool) -- if true will use tests end-point (default False)
         """
         base_url = self._wrapper_test(test)
         url = base_url + URLResources.QUERY_COUNT_ENTITY
         return self._count_query_wrapper(url, query)
 
     def count_entity_total(self, test=False):
-        """Make a count entity total query"""
+        """Make a count entity total query
+
+        test(bool) -- if true will use tests end-point (default False)
+        """
         base_url = self._wrapper_test(test)
         url = base_url + URLResources.QUERY_COUNT_ENTITY_TOTAL
         return self._make_request(
@@ -231,6 +240,7 @@ def count_event(self, query, test=False):
 
         Keyword arguments:
         data -- A dictionary query
+        test(bool) -- if true will use tests end-point (default False)
         """
         base_url = self._wrapper_test(test)
         url = base_url + URLResources.QUERY_COUNT_EVENT
@@ -240,7 +250,8 @@ def aggregation(self, query, test=False):
         """Make a aggregation query
 
         Keyword arguments:
-        data -- A dictionary query
+        query -- An aggregation query
+        test(bool) -- if true will use tests end-point (default False)
         """
         base_url = self._wrapper_test(test)
         url = base_url + URLResources.QUERY_AGGREGATION
@@ -262,6 +273,7 @@ def top_values(self, query, test=False):
 
         Keyword arguments:
         query -- A dictionary query
+        test(bool) -- if true will use tests end-point (default False)
         """
         base_url = self._wrapper_test(test)
         url = base_url + URLResources.QUERY_TOP_VALUES
@@ -278,6 +290,7 @@ def exists_entity(self, ids, test=False):
 
         Keyword arguments:
         ids -- A list with entity to check if exists
+        test(bool) -- if true will use tests end-point (default False)
         """
         base_url = self._wrapper_test(test)
         url = base_url + URLResources.QUERY_EXISTS_ENTITY
@@ -297,7 +310,8 @@ def get_saved_query(self, query_name, test=False):
         """Get a saved query
 
         Keyword arguments:
-        query_name(string) -- A string with query name
+        query_name(string) -- The name of the saved query
+        test(bool) -- if true will use tests end-point (default False)
         """
         base_url = self._wrapper_test(test)
         url = base_url + URLResources.QUERY_SAVED + query_name
@@ -310,7 +324,8 @@ def get_saved_queries(self, test=False):
         """Get all saved queries
 
         Keyword arguments:
-        query_name(string) -- A string with query name
+        query_name(string) -- The name of the saved query
+        test(bool) -- if true will use tests end-point (default False)
         """
         base_url = self._wrapper_test(test)
         url = base_url + URLResources.QUERY_SAVED
@@ -323,7 +338,8 @@ def delete_saved_query(self, query_name, test=False):
         """Delete a saved query
 
         Keyword arguments:
-        query_name(string) -- A string with query name
+        query_name(string) -- The name of the saved query
+        test(bool) -- if true will use tests end-point (default False)
         """
         base_url = self._wrapper_test(test)
         url = base_url + URLResources.QUERY_SAVED + query_name
@@ -338,6 +354,7 @@ def create_saved_query(self, query, test=False):
 
         Keyword arguments:
         query -- A dictionary query
+        test(bool) -- if true will use tests end-point (default False)
         """
         base_url = self._wrapper_test(test)
         url = base_url + URLResources.QUERY_SAVED
@@ -347,8 +364,9 @@ def update_saved_query(self, name, query, test=False):
         """Get a list of queries saved
 
         Keyword arguments:
-        name -- A dictionary query
+        name -- The name of the saved query to update
         query -- A dictionary query
+        test(bool) -- if true will use tests end-point (default False)
         """
         base_url = self._wrapper_test(test)
         url = base_url + URLResources.QUERY_SAVED + name
@@ -359,16 +377,18 @@ def result(self, query, test=False):
 
         Keyword arguments:
         query -- A dictionary query
+        test(bool) -- if true will use tests end-point (default False)
         """
         base_url = self._wrapper_test(test)
         url = base_url + URLResources.QUERY_DATA_EXTRACTION_RESULT
         return self._data_extraction_wrapper(url, query)
 
     def score(self, query, test=False):
-        """Get a data extraction result
+        """Get a data extraction score
 
         Keyword arguments:
         query -- A dictionary query
+        test(bool) -- if true will use tests end-point (default False)
         """
         base_url = self._wrapper_test(test)
         url = base_url + URLResources.QUERY_DATA_EXTRACTION_SCORE

pyslicer/core/requester.py

@@ -26,7 +26,7 @@ def post(self, url, data, headers):
             raise exceptions.SlicingDiceHTTPError(e)
 
     def put(self, url, data, headers):
-        """Returns a post request result object"""
+        """Returns a put request result object"""
         try:
             return requests.put(
                 url,

pyslicer/utils/validators.py

@@ -48,7 +48,7 @@ def _has_valid_type(self):
     def validator(self):
         """
         Returns:
-            true if query is valid
+            true if saved query is valid
         """
         if self._has_valid_type():
             return True
@@ -64,6 +64,10 @@ def __init__(self, queries):
         super(QueryCountValidator, self).__init__(queries)
 
     def validator(self):
+        """
+        Returns:
+            true if count query is valid
+        """
         if len(self.data) > 10:
             raise exceptions.MaxLimitException(
                 "The query count entity has a limit of 10 queries by request.")
@@ -83,6 +87,7 @@ def exceeds_queries_limit(self):
 
         Returns:
             true if exceeds the limit
+            false otherwise
         """
         if len(self.data) > 5:
             return True
@@ -136,6 +141,11 @@ def __init__(self, queries):
         super(QueryDataExtractionValidator, self).__init__(queries)
 
     def _valid_keys(self):
+        """Validate a data extraction query
+
+        Returns:
+            true if query is valid
+        """
         if "fields" in self.data:
             value = self.data["fields"]
             if not isinstance(value, list):
@@ -246,8 +256,8 @@ def _validate_field_type(self):
             raise exceptions.InvalidFieldTypeException(
                 "This field have a invalid type.")
 
-    def _validate_field_decimal_places(self):
-        """Validate field decimal places"""
+    def _validate_field_decimal_type(self):
+        """Validate field decimal type"""
         decimal_types = ["decimal", "decimal-time-series"]
         if self.data['type'] not in decimal_types:
             raise exceptions.InvalidFieldException(
@@ -284,7 +294,5 @@ def validator(self):
         if 'description' in self.data:
             self._validate_description()
         if 'decimal-place' in self.data:
-            self._validate_field_decimal_places()
-        # if 'storage' in self.data:
-        #    self._validate_field_storage()
+            self._validate_field_decimal_type()
         return True