some documentation

ckanext/datastore/backend/__init__.py

@@ -11,10 +11,16 @@
 
 
 def get_all_resources_ids_in_datastore():
+    """
+    Helper for getting id of all resources in datastore.
+
+    Uses `get_all_ids` of active datastore backend.
+    """
     DatastoreBackend.register_backends()
     DatastoreBackend.set_active_backend(config)
     backend = DatastoreBackend.get_active_backend()
     backend.configure(config)
+
     return backend.get_all_ids()
 
 
@@ -50,59 +56,124 @@ class InvalidDataError(Exception):
 
 
 class DatastoreBackend:
+    """Base class for all datastore backends.
+
+    :prop _backend: mapping(schema, class) of all registered backends
+    :type _backend: dictonary
+    :prop _active_backend: current active backend
+    :type _active_backend: DatastoreBackend
+    """
 
     _backends = {}
     _active_backend = None
 
     @classmethod
     def register_backends(cls):
+        """Register all backend implementations inside extensions."""
         for plugin in plugins.PluginImplementations(IDatastoreBackend):
             cls._backends.update(plugin.register_backends())
 
     @classmethod
     def set_active_backend(cls, config):
+        """Choose most suitable backend depending on configuration
+
+        :param config: configuration object
+        :rtype: ckan.common.CKANConfig
+
+        """
         schema = config.get('ckan.datastore.write_url').split(':')[0]
         cls._active_backend = cls._backends[schema]()
 
     @classmethod
     def get_active_backend(cls):
+        """Return currently used backend"""
         return cls._active_backend
 
     def configure(self, config):
+        """Configure backend, set inner variables, make some initial setup.
+
+        :param config: configuration object
+        :returns: config
+        :rtype: CKANConfig
+
+        """
+
         return config
 
     def create(self, context, data_dict):
+        """Create new resourct inside datastore.
+
+        Called by `datastore_create`.
+        """
+
         raise NotImplementedError()
 
     def upsert(self, context, data_dict):
+        """Update or create resource depending on data_dict param.
+
+        Called by `datastore_upsert`.
+        """
         raise NotImplementedError()
 
     def delete(self, context, data_dict):
+        """Remove resource from datastore.
+
+        Called by `datastore_delete`.
+        """
         raise NotImplementedError()
 
     def search(self, context, data_dict):
+        """Base search.
+
+        Called by `datastore_search`.
+        """
         raise NotImplementedError()
 
     def search_sql(self, context, data_dict):
+        """Advanced search.
+
+        Called by `datastore_search_sql`.
+        """
         raise NotImplementedError()
 
     def make_private(self, context, data_dict):
+        """Do not display resource in search results.
+
+        Called by `datastore_make_private`.
+        """
         raise NotImplementedError()
 
     def make_public(self, context, data_dict):
+        """Enable serch for resource.
+
+        Called by `datastore_make_public`.
+        """
         raise NotImplementedError()
 
     def resource_exists(self, id):
+        """Define whether resource exists in datastore.
+        """
         raise NotImplementedError()
 
     def resource_fields(self, id):
+        """Return dictonary with resource description.
+
+        Called by `datastore_info`.
+        :returns: dictonary with nested dicts `schema` and `meta`
+        """
         raise NotImplementedError()
 
     def resource_info(self, id):
+        """Return DataDictonary with resource's info - #3414
+        """
         raise NotImplementedError()
 
     def resource_id_from_alias(self, alias):
+        """Convert resource's alias to real id.
+        """
         raise NotImplementedError()
 
     def get_all_ids(self):
+        """Return id of all resource registered in datastore.
+        """
         raise NotImplementedError()

ckanext/datastore/interfaces.py

@@ -148,11 +148,22 @@ def datastore_delete(self, context, data_dict, fields_types, query_dict):
 
 
 class IDatastoreBackend(interfaces.Interface):
-
+    """Allow custom implementations of datastore backend"""
     def register_backends(self):
         """
-        Initial configuration and any assertions based on config.
+        Register classes that inherits from DatastoreBackend.
+
+        Every registered class provides implementations of DatastoreBackend
+        and, depending on `datastore.write_url`, one of them will be used
+        inside actions.
+
+        `ckanext.datastore.DatastoreBackend` has method `set_active_backend`
+        which will define most suitable backend depending on schema of
+        `ckan.datastore.write_url` config directive. eg. 'postgresql://a:b@x'
+        will use 'postgresql' backend, but 'mongodb://a:b@c' will try to use
+        'mongodb' backend(if such backend has been registered, of course).
 
-        Takes `config` object from IConfigurable.configure method
+        :returns: the dictonary with backend name as key and backend class as
+                  value
         """
         return {}