commit a2ef112e08228d5878fca01e0f201e279c869ee8
Author: Stavros Sachtouris <saxtouri@admin.grnet.gr>
Date:   Fri Nov 30 16:06:05 2012 +0200

    Update kamaki.clients.compute commends + restruct

diff --git a/kamaki/clients/compute.py b/kamaki/clients/compute.py
index b6a3620..bbd0c68 100644
--- a/kamaki/clients/compute.py
+++ b/kamaki/clients/compute.py
@@ -41,27 +41,40 @@ class ComputeClient(ComputeClientApi):
     """OpenStack Compute API 1.1 client"""
 
     def list_servers(self, detail=False):
-        """List servers, returned detailed output if detailed is True"""
+        """
+        :param detail: if true, append full server details to each item
+
+        :returns: list of server ids and names
+        """
         detail = 'detail' if detail else ''
         r = self.servers_get(command=detail)
         return r.json['servers']['values']
 
     def get_server_details(self, server_id, **kwargs):
-        """Return detailed output on a server specified by its id"""
+        """Return detailed info for a server
+
+        :param server_id: integer (int or str)
+
+        :returns: dict with server details
+        """
         r = self.servers_get(server_id, **kwargs)
         return r.json['server']
 
     def create_server(self, name, flavor_id, image_id, personality=None):
         """Submit request to create a new server
 
-        The flavor_id specifies the hardware configuration to use,
-        the image_id specifies the OS Image to be deployed inside the new
-        server.
+        :param name: (str)
+
+        :param flavor_id: integer id denoting a preset hardware configuration
+
+        :param image_id: (str) id denoting the OS image to run on the VM
 
-        The personality argument is a list of (file path, file contents)
-        tuples, describing files to be injected into the server upon creation.
+        :param personality: a list of (file path, file contents) tuples,
+            describing files to be injected into VM upon creation.
 
-        The call returns a dictionary describing the newly created server.
+        :returns: a dict with the new VMs details
+
+        :raises ClientError: wraps request errors
         """
         req = {'server': {'name': name,
                           'flavorRef': flavor_id,
@@ -94,33 +107,58 @@ class ComputeClient(ComputeClientApi):
         return r.json['server']
 
     def update_server_name(self, server_id, new_name):
-        """Update the name of the server as reported by the API.
+        """Update the name of the server as reported by the API (does not
+            modify the hostname used inside the VM)
+
+        :param server_id: integer (str or int)
 
-        This call does not modify the hostname actually used by the server
-        internally.
+        :param new_name: (str) 
         """
         req = {'server': {'name': new_name}}
         r = self.servers_put(server_id, json_data=req)
         r.release()
 
     def delete_server(self, server_id):
-        """Submit a deletion request for a server specified by id"""
+        """Submit a deletion request for a server specified by id
+
+        :param server_id: integer (str or int)
+        """
         r = self.servers_delete(server_id)
         r.release()
 
     def reboot_server(self, server_id, hard=False):
-        """Submit a reboot request for a server specified by id"""
+        """
+        :param server_id: integer (str or int)
+
+        :param hard: perform a hard reboot if true, soft reboot otherwise
+        """
         type = 'HARD' if hard else 'SOFT'
         req = {'reboot': {'type': type}}
         r = self.servers_post(server_id, 'action', json_data=req)
         r.release()
 
     def get_server_metadata(self, server_id, key=''):
+        """
+        :param server_id: integer (str or int)
+
+        :param key: (str) the metadatum key (all metadata if not given)
+
+        :returns: a key:val dict of requests metadata
+        """
         command = path4url('meta', key)
         r = self.servers_get(server_id, command)
         return r.json['meta'] if key != '' else r.json['metadata']['values']
 
     def create_server_metadata(self, server_id, key, val):
+        """
+        :param server_id: integer (str or int)
+
+        :param key: (str)
+
+        :param val: (str)
+
+        :returns: dict of updated key:val metadata
+        """
         req = {'meta': {key: val}}
         r = self.servers_put(server_id,
             'meta/' + key,
@@ -129,88 +167,63 @@ class ComputeClient(ComputeClientApi):
         return r.json['meta']
 
     def update_server_metadata(self, server_id, **metadata):
+        """
+        :param server_id: integer (str or int)
+
+        :param metadata: dict of key:val metadata
+
+        :returns: dict of updated key:val metadata
+        """
         req = {'metadata': metadata}
         r = self.servers_post(server_id, 'meta', json_data=req, success=201)
         return r.json['metadata']
 
     def delete_server_metadata(self, server_id, key):
+        """
+        :param server_id: integer (str or int)
+
+        :param key: (str) the meta key
+        """
         r = self.servers_delete(server_id, 'meta/' + key)
         r.release()
 
-    def flavors_get(self, flavor_id='', command='', **kwargs):
-        """GET base_url[/flavor_id][/command]
-        @param flavor_id
-        @param command
+    def list_flavors(self, detail=False):
         """
-        path = path4url('flavors', flavor_id, command)
-        success = kwargs.pop('success', 200)
-        return self.get(path, success=success, **kwargs)
+        :param detail: (bool) detailed flavor info if set, short if not
 
-    def list_flavors(self, detail=False):
+        :returns: (dict) flavor info
+        """
         detail = 'detail' if detail else ''
         r = self.flavors_get(command='detail')
         return r.json['flavors']['values']
 
     def get_flavor_details(self, flavor_id):
+        """
+        :param flavor_id: integer (str or int)
+
+        :returns: dict
+        """
         r = self.flavors_get(flavor_id)
         return r.json['flavor']
 
-    def images_get(self, image_id='', command='', **kwargs):
-        """GET base_url[/image_id][/command]
-        @param image_id
-        @param command
-        """
-        path = path4url('images', image_id, command)
-        success = kwargs.pop('success', 200)
-        return self.get(path, success=success, **kwargs)
-
-    def images_delete(self, image_id='', command='', **kwargs):
-        """DEL ETE base_url[/image_id][/command]
-        @param image_id
-        @param command
-        """
-        path = path4url('images', image_id, command)
-        success = kwargs.pop('success', 204)
-        return self.delete(path, success=success, **kwargs)
-
-    def images_post(self, image_id='', command='', json_data=None, **kwargs):
-        """POST base_url/images[/image_id]/[command] request
-        @param image_id or ''
-        @param command: can be 'action' or ''
-        @param json_data: a json valid dict that will be send as data
-        """
-        data = json_data
-        if json_data is not None:
-            data = json.dumps(json_data)
-            self.set_header('Content-Type', 'application/json')
-            self.set_header('Content-Length', len(data))
-
-        path = path4url('images', image_id, command)
-        success = kwargs.pop('success', 201)
-        return self.post(path, data=data, success=success, **kwargs)
-
-    def images_put(self, image_id='', command='', json_data=None, **kwargs):
-        """PUT base_url/images[/image_id]/[command] request
-        @param image_id or ''
-        @param command: can be 'action' or ''
-        @param json_data: a json valid dict that will be send as data
-        """
-        data = json_data
-        if json_data is not None:
-            data = json.dumps(json_data)
-            self.set_header('Content-Type', 'application/json')
-            self.set_header('Content-Length', len(data))
-
-        path = path4url('images', image_id, command)
-        success = kwargs.pop('success', 201)
-        return self.put(path, data=data, success=success, **kwargs)
-
     def list_images(self, detail=False):
+        """
+        :param detail: (bool) detailed info if set, short if not
+
+        :returns: dict id,name + full info if detail
+        """
         detail = 'detail' if detail else ''
         r = self.images_get(command=detail)
         return r.json['images']['values']
 
     def get_image_details(self, image_id, **kwargs):
+        """
+        :param image_id: integer (str or int)
+
+        :returns: dict
+
+        :raises ClientError: 404 if image not available
+        """
         r = self.images_get(image_id, **kwargs)
         try:
             return r.json['image']
@@ -219,25 +232,56 @@ class ComputeClient(ComputeClientApi):
                 details='Image %d not found or not accessible')
 
     def delete_image(self, image_id):
+        """
+        :param image_id: (str)
+        """
         r = self.images_delete(image_id)
         r.release()
 
     def get_image_metadata(self, image_id, key=''):
+        """
+        :param image_id: (str)
+
+        :param key: (str) the metadatum key
+
+        :returns (dict) metadata if key not set, specific metadatum otherwise
+        """
         command = path4url('meta', key)
         r = self.images_get(image_id, command)
-        return r.json['meta'] if key != '' else r.json['metadata']['values']
+        return r.json['meta'] if key else r.json['metadata']['values']
 
     def create_image_metadata(self, image_id, key, val):
+        """
+        :param image_id: integer (str or int)
+
+        :param key: (str) metadatum key
+
+        :param val: (str) metadatum value
+
+        :returns: (dict) updated metadata
+        """
         req = {'meta': {key: val}}
         r = self.images_put(image_id, 'meta/' + key, json_data=req)
         return r.json['meta']
 
     def update_image_metadata(self, image_id, **metadata):
+        """
+        :param image_id: (str)
+
+        :param metadata: dict
+
+        :returns: updated metadata
+        """
         req = {'metadata': metadata}
         r = self.images_post(image_id, 'meta', json_data=req)
         return r.json['metadata']
 
     def delete_image_metadata(self, image_id, key):
+        """
+        :param image_id: (str)
+
+        :param key: (str) metadatum key
+        """
         command = path4url('meta', key)
         r = self.images_delete(image_id, command)
         r.release()
