updates in documentation

ckanext/datastore/backend/__init__.py

@@ -108,49 +108,89 @@ def create(self, context, data_dict):
         """Create new resourct inside datastore.
 
         Called by `datastore_create`.
-        """
 
+        :param data_dict: See `ckanext.datastore.logic.action.datastore_create`
+        :returns: The newly created data object
+        :rtype: dictonary
+        """
         raise NotImplementedError()
 
     def upsert(self, context, data_dict):
         """Update or create resource depending on data_dict param.
 
         Called by `datastore_upsert`.
+
+        :param data_dict: See `ckanext.datastore.logic.action.datastore_upsert`
+        :returns: The modified data object
+        :rtype: dictonary
         """
         raise NotImplementedError()
 
     def delete(self, context, data_dict):
         """Remove resource from datastore.
 
         Called by `datastore_delete`.
+
+        :param data_dict: See `ckanext.datastore.logic.action.datastore_delete`
+        :returns: Original filters sent.
+        :rtype: dictonary
         """
         raise NotImplementedError()
 
     def search(self, context, data_dict):
         """Base search.
 
         Called by `datastore_search`.
+
+        :param data_dict: See `ckanext.datastore.logic.action.datastore_search`
+        :rtype: dictonary with following keys
+
+        :param fields: fields/columns and their extra metadata
+        :type fields: list of dictionaries
+        :param offset: query offset value
+        :type offset: int
+        :param limit: query limit value
+        :type limit: int
+        :param filters: query filters
+        :type filters: list of dictionaries
+        :param total: number of total matching records
+        :type total: int
+        :param records: list of matching results
+        :type records: list of dictionaries
+
         """
         raise NotImplementedError()
 
     def search_sql(self, context, data_dict):
         """Advanced search.
 
         Called by `datastore_search_sql`.
+        :param sql: a single seach statement
+        :type sql: string
+
+        :rtype: dictonary
+        :param fields: fields/columns and their extra metadata
+        :type fields: list of dictionaries
+        :param records: list of matching results
+        :type records: list of dictionaries
         """
         raise NotImplementedError()
 
     def make_private(self, context, data_dict):
         """Do not display resource in search results.
 
         Called by `datastore_make_private`.
+        :param resource_id: id of resource that should become private
+        :type resource_id: string
         """
         raise NotImplementedError()
 
     def make_public(self, context, data_dict):
         """Enable serch for resource.
 
         Called by `datastore_make_public`.
+        :param resource_id: id of resource that should become public
+        :type resource_id: string
         """
         raise NotImplementedError()
 
@@ -163,7 +203,7 @@ def resource_fields(self, id):
         """Return dictonary with resource description.
 
         Called by `datastore_info`.
-        :returns: dictonary with nested dicts `schema` and `meta`
+        :returns: A dictionary describing the columns and their types.
         """
         raise NotImplementedError()
 
@@ -174,10 +214,19 @@ def resource_info(self, id):
 
     def resource_id_from_alias(self, alias):
         """Convert resource's alias to real id.
+
+        :param alias: resource's alias or id
+        :type alias: string
+        :returns: real id of resource
+        :rtype: string
+
         """
         raise NotImplementedError()
 
     def get_all_ids(self):
         """Return id of all resource registered in datastore.
+
+        :returns: all resources ids
+        :rtype: list of strings
         """
         raise NotImplementedError()

ckanext/datastore/backend/example.py

@@ -1,6 +1,5 @@
 # -*- coding: utf-8 -*-
 
-import re
 import logging
 from sqlalchemy import create_engine
 
@@ -32,7 +31,6 @@ def _insert_records(self, table, records):
                 )
             pass
 
-
     def configure(self, config):
         self.write_url = config.get(
             'ckan.datastore.write_url').replace('example-', '')
@@ -56,7 +54,7 @@ def upsert(self, context, data_dict):
 
     def delete(self, context, data_dict):
         engine = self._get_engine()
-        result = engine.execute('DROP TABLE IF EXISTS "{0}"'.format(
+        engine.execute('DROP TABLE IF EXISTS "{0}"'.format(
             data_dict['resource_id']
         ))
         return data_dict
@@ -70,7 +68,15 @@ def search(self, context, data_dict):
 
         data_dict['records'] = map(dict, result.fetchall())
         data_dict['total'] = len(data_dict['records'])
-        data_dict['fields'] = self.resource_fields(data_dict['resource_id'])
+
+        fields_info = []
+        for name, type in self.resource_fields(
+                data_dict['resource_id'])['schema'].items():
+            fields_info.append({
+                'type': type,
+                'id': name
+            })
+        data_dict['fields'] = fields_info
         return data_dict
 
     def search_sql(self, context, data_dict):
@@ -91,19 +97,13 @@ def resource_exists(self, id):
         ).fetchone()
 
     def resource_fields(self, id):
-        result = []
         engine = self._get_engine()
         info = engine.execute('PRAGMA table_info("{0}")'.format(id)).fetchall()
 
+        schema = {}
         for col in info:
-            result.append({
-                'type': col.type,
-                'id': col.name
-            })
-        return result
-
-    def resource_info(self, id):
-        raise NotImplementedError()
+            schema[col.name] = col.type
+        return {'schema': schema, 'meta': {}}
 
     def resource_id_from_alias(self, alias):
         if self.resource_exists(alias):