KAB-46 fix docblocks

Author: tomasfejfar

kbcstorage/configurations_metadata.py

@@ -1,20 +1,20 @@
 """
-Manages calls to the Storage API relating to configurations
+Manages calls to the Storage API relating to configurations metadata
 
-Full documentation https://keboola.docs.apiary.io/#reference/components-and-configurations
+Full documentation https://keboola.docs.apiary.io/#reference/metadata/components-configurations-metadata/
 """
 import json
 from kbcstorage.base import Endpoint
 
 
 class ConfigurationsMetadata(Endpoint):
     """
-    Configurations Endpoint
+    Configurations metadata Endpoint
     """
 
     def __init__(self, root_url, token, branch_id):
         """
-        Create a Component endpoint.
+        Create a Component metadata endpoint.
 
         Args:
             root_url (:obj:`str`): The base url for the API.
@@ -23,37 +23,18 @@ def __init__(self, root_url, token, branch_id):
         """
         super().__init__(root_url, f"branch/{branch_id}/components", token)
 
-    def detail(self, component_id, configuration_id):
-        """
-        Retrieves information about a given configuration.
-
-        Args:
-            component_id (str): The id of the component.
-            configuration_id (str): The id of the configuration.
-
-        Returns:
-            response_body: The parsed json from the HTTP response.
-
-        Raises:
-            requests.HTTPError: If the API request fails.
-        """
-        if not isinstance(component_id, str) or component_id == '':
-            raise ValueError("Invalid component_id '{}'.".format(component_id))
-        if not isinstance(configuration_id, str) or configuration_id == '':
-            raise ValueError("Invalid component_id '{}'.".format(configuration_id))
-        url = '{}/{}/configs/{}'.format(self.base_url, component_id, configuration_id)
-        return self._get(url)
-
     def delete(self, component_id, configuration_id, metadata_id):
         """
-        Deletes the configuration.
+        Deletes the configuration metadata identified by ``metadata_id``.
 
         Args:
             component_id (str): The id of the component.
             configuration_id (str): The id of the configuration.
+            metadata_id (str): The id of the metadata (not key!).
 
         Raises:
             requests.HTTPError: If the API request fails.
+            ValueError: If the component_id/configuration_id/metadata_id is not a string or is empty.
         """
         if not isinstance(component_id, str) or component_id == '':
             raise ValueError("Invalid component_id '{}'.".format(component_id))
@@ -66,34 +47,41 @@ def delete(self, component_id, configuration_id, metadata_id):
 
     def list(self, component_id, configuration_id):
         """
-        Lists configurations of the given component.
+        Lists metadata for a given component configuration.
 
         Args:
             component_id (str): The id of the component.
+            configuration_id (str): The id of the configuration.
 
         Raises:
             requests.HTTPError: If the API request fails.
+            ValueError: If the component_id/configuration_id is not a string or is empty.
         """
         if not isinstance(component_id, str) or component_id == '':
             raise ValueError("Invalid component_id '{}'.".format(component_id))
+        if not isinstance(configuration_id, str) or configuration_id == '':
+            raise ValueError("Invalid configuration_id '{}'.".format(configuration_id))
         url = '{}/{}/configs/{}/metadata'.format(self.base_url, component_id, configuration_id)
         return self._get(url)
 
     def create(self, component_id, configuration_id, provider, metadata):
         """
-        Create a new configuration.
+        Writes metadata for a given component configuration.
 
         Args:
             component_id (str): The id of the component.
             configuration (str): The id of the configuration.
             provider (str): The provider of the configuration (currently ignored and "user" is sent).
-            key (str): The key of the configuration.
-            value (str): The value of the configuration.
+            metadata (list): A list of metadata items. Item is a dictionary with 'key' and 'value' keys.
+
         Returns:
             response_body: The parsed json from the HTTP response.
 
         Raises:
             requests.HTTPError: If the API request fails.
+            ValueError: If the component_id/configuration_id is not a string or is empty.
+            ValueError: If the metadata is not a list.
+            ValueError: If the metadata item is not a dictionary.
         """
         if not isinstance(component_id, str) or component_id == '':
             raise ValueError("Invalid component_id '{}'.".format(component_id))

kbcstorage/tables_metadata.py

@@ -16,7 +16,7 @@ class TablesMetadata(Endpoint):
     """
     def __init__(self, root_url, token):
         """
-        Create a Tables endpoint.
+        Create a Tables metadata endpoint.
 
         Args:
             root_url (:obj:`str`): The base url for the API.
@@ -28,6 +28,9 @@ def list(self, table_id):
         """
         List all metadata for table
 
+        Args:
+            table_id (str): Table id
+
         Returns:
             response_body: The parsed json from the HTTP response.
 
@@ -44,14 +47,15 @@ def list(self, table_id):
 
     def delete(self, table_id, metadata_id):
         """
-        Delete a table referenced by ``table_id``.
+        Delete a table metadata referenced by ``metadata_id``.
 
         Args:
-            table_id (str): The id of the table to be deleted.
+            table_id (str): The id of the table.
+            metadata_id (str): The id of the table metdata entry to be deleted.
 
         Raises:
             requests.HTTPError: If the API request fails.
-            ValueError: If the table_id is not a string or is empty.
+            ValueError: If the table_id/metadata_id is not a string or is empty.
         """
         if not isinstance(table_id, str) or table_id == '':
             raise ValueError("Invalid table_id '{}'.".format(table_id))
@@ -70,13 +74,17 @@ def create(self, table_id, provider, metadata, columns_metadata):
             table_id (str): Table id
             provider (str): Provider of the metadata
             metadata (list): List of metadata dictionaries with 'key' and 'value'
-            columns_metadata (dict): Dictionary with column metadata
+            columns_metadata (dict): Dictionary with lists of metadata dictionaries with 'key', 'value', 'columnName'.
 
         Returns:
             response_body: The parsed json from the HTTP response.
 
         Raises:
             requests.HTTPError: If the API request fails.
+            ValueError: If the table_id is not a string or is empty.
+            ValueError: If the provider is not a string or is empty.
+            ValueError: If the metadata is not a list.
+            ValueError: If the columns_metadata is not a list
         """
         if not isinstance(table_id, str) or table_id == '':
             raise ValueError("Invalid table_id '{}'.".format(table_id))