Documentation on the lodel.plugins.dummy_datasource plugin

lodel/plugins/dummy_datasource/__init__.py

@@ -1,14 +1,23 @@
+## @package lodel.plugins.dummy_datasource Example of a datasource type plugin
+
+# Here we use the Lodel Context Manager to expose the modules which are specific to the application
 from lodel.context import LodelContext
 LodelContext.expose_modules(globals(), {
     'lodel.validator.validator': ['Validator']})
 from .datasource import DummyDatasource as Datasource
 
+## @brief plugin's category
 __plugin_type__ = 'datasource'
+## @brief plugin's name (matching the package's name)
 __plugin_name__ = "dummy_datasource"
+## @brief plugin's version
 __version__ = '0.0.1'
+## @brief plugin's main entry module
 __loader__ = 'main.py'
+## @brief plugin's dependances
 __plugin_deps__ = []
 
+## @brief Plugin's configuration options and their corresponding validators
 CONFSPEC = {
     'lodel2.datasource.dummy_datasource.*' : {
         'dummy': (  None,

lodel/plugins/dummy_datasource/datasource.py

@@ -1,51 +1,56 @@
 #-*- coding:utf-8 -*-
 
+## @package lodel.plugins.dummy_datasource.datasource This module contains the main class of the datasource, implementing the basic operations one can perform.
+
 from lodel.context import LodelContext
 LodelContext.expose_modules(globals(), {
     'lodel.plugin.datasource_plugin': ['AbstractDatasource']})
 
+## @brief Datasource class, inherited from @ref lodel.plugin.datasource.AbstractDatasource
 class DummyDatasource(AbstractDatasource):
     
+    ##
+    # @param conn_args list
+    # @param conn_kwargs dict
     def __init__(self, *conn_args, **conn_kwargs):
         self.conn_args = conn_args
         self.conn_kwargs = conn_kwargs
     
-    ##@brief Provide a new uniq numeric ID
-    #@param emcomp LeObject subclass (not instance) : To know on wich things we
-    #have to be uniq
-    #@return an integer
+    ## @brief Provides a new unique numeric ID
+    # @param emcomp LeObject subclass (not instance) : The class against whom we have to be unique
+    # @return an integer
     def new_numeric_id(self, emcomp):
         pass
 
-    ##@brief returns a selection of documents from the datasource
-    #@param target Emclass
-    #@param field_list list
-    #@param filters list : List of filters
-    #@param relational_filters list : List of relational filters
-    #@param order list : List of column to order. ex: order = [('title', 'ASC'),]
-    #@param group list : List of tupple representing the column to group together. ex: group = [('title', 'ASC'),]
-    #@param limit int : Number of records to be returned
-    #@param offset int: used with limit to choose the start record
-    #@param instanciate bool : If true, the records are returned as instances, else they are returned as dict
-    #@return list
+    ## @brief returns a selection of documents from the datasource
+    # @param target Emclass
+    # @param field_list list
+    # @param filters list : List of filters
+    # @param relational_filters list : List of relational filters (default value : None)
+    # @param order list : List of column to order. ex: order = [('title', 'ASC'),] (default value : None)
+    # @param group list : List of tupple representing the column to group together. ex: group = [('title', 'ASC'),] (default value : None)
+    # @param limit int : Number of records to be returned (default value : None)
+    # @param offset int: used with limit to choose the start record (default value : 0)
+    # @param instanciate bool : If true, the records are returned as instances, else they are returned as dict (default value : True)
+    # @return list
     def select(self, target, field_list, filters, relational_filters=None, order=None, group=None, limit=None, offset=0,
                instanciate=True):
         pass
 
-    ##@brief Deletes records according to given filters
-    #@param target Emclass : class of the record to delete
-    #@param filters list : List of filters
-    #@param relational_filters list : List of relational filters
-    #@return int : number of deleted records
+    ## @brief Deletes records according to given filters
+    # @param target Emclass : class of the record to delete
+    # @param filters list : List of filters
+    # @param relational_filters list : List of relational filters
+    # @return int : number of deleted records
     def delete(self, target, filters, relational_filters):
         return 0
 
     ## @brief updates records according to given filters
-    #@param target Emclass : class of the object to insert
-    #@param filters list : List of filters
-    #@param relational_filters list : List of relational filters
-    #@param upd_datas dict : datas to update (new values)
-    #@return int : Number of updated records
+    # @param target Emclass : class of the object to insert
+    # @param filters list : List of filters
+    # @param relational_filters list : List of relational filters
+    # @param upd_datas dict : datas to update (new values)
+    # @return int : Number of updated records
     def update(self, target, filters, relational_filters, upd_datas):
         return 0
 

lodel/plugins/dummy_datasource/main.py

@@ -1,10 +1,14 @@
 #-*- coding:utf-8 -*-
 
+## @package lodel.plugins.dummy_datasource.main The main module of the plugin. 
+
 from lodel.context import LodelContext
 LodelContext.expose_modules(globals(), {
     'lodel.plugin': ['LodelHook']})
 from .datasource import DummyDatasource as Datasource
 
+## @brief returns the migration handler of this plugin. 
+# @retunr DummyMigrationHandler
 def migration_handler_class():
     from .migration_handler import DummyMigrationHandler as migration_handler
     return migration_handler

lodel/plugins/dummy_datasource/migration_handler.py

@@ -1,22 +1,39 @@
 #-*- coding: utf-8 -*-
 
-##@brief Abtract class for migration handlers
+## @package lodel.plugins.dummy_datasource.migration_handler Migration handler of the datasource plugin. 
+#
+# The migration handler is here to report the changes made in the editorial model to the data source. 
+# 
+# For a database, it could be the creation/deletion of tables, the addition/deletion/change of certain columns, etc...
+#
+# We also have here the datasource initialization process, for the first use of it. The migration handler will then
+# use the editorial model to generate the corresponding data storage. 
+
+## @brief Abtract class for migration handlers
 class DummyMigrationHandler(object):
 
-    ##@brief Create a new migration handler given DB connection options
+    ## @brief Create a new migration handler given DB connection options
     def __init__(self, *args, **kwargs):
         pass
     
-    ##@brief DB initialisation
-    #@param emclass_list list : list of EmClasses concerned by this MH
+    ## @brief DB initialisation
+    # @param emclass_list list : list of EmClasses concerned by this MH
     def init_db(self, emclass_list):
         pass
     
-    ##@todo redefine
+    ## @brief register a change in the editorial model
+    # @param model EditorialModel
+    # @param uid
+    # @param initial_state
+    # @param new_state
+    # @todo redefine
     def register_change(self, model, uid, initial_state, new_state):
         pass
 
-    ##@todo redefine
+    ##
+    # @param em EditorialModel
+    # @param state_hash str
+    # @todo redefine
     def register_model_state(self, em, state_hash):
         pass