Updated the DummyDatasource + documenting query filters

leobject/datasources/dummy.py

@@ -1,10 +1,9 @@
 #-*- coding: utf-8 -*-
 
-
-## dummy datasource for LeObject
+## @brief Dummy datasource for LeObject
+#
 # This class has to be extended to apply to a real datasource
 # But it can be used as an empty and debug datasource
-
 class DummyDatasource(object):
 
     def __init__(self, module=None, *conn_args, **conn_kargs):
@@ -13,39 +12,42 @@ class DummyDatasource(object):
         self.conn_kargs = conn_kargs
 
     ## @brief update an existing LeObject
-    # @param lodel_id (int) : list of lodel_id
-    # @param checked_data dict
-    # @param filters
-    # @param relational_filters
-    def update(self, lodel_id, checked_data, filters, relational_filters):
+    # @param letype LeType : LeType child class
+    # @param leclass LeClass : LeClass child class
+    # @param filters list : List of filters (see @ref leobject_filters )
+    # @param rel_filters list : List of relationnal filters (see @ref leobject_filters )
+    # @param data dict : Dict representing fields and there values
+    # @return True if success
+    def update(self, letype, leclass, filters, rel_filters, data):
         print ("DummyDatasource.update: ", lodel_id, checked_data, filters, relational_filters)
         return True
 
     ## @brief create a new LeObject
-    # @param letype LeType
-    # @param leclass LeClass
-    # @param data dict: a dictionnary of field:value to save
+    # @param letype LeType : LeType child class
+    # @param leclass LeClass : LeClass child class
+    # @param data list: a lis of dictionnary of field:value to save
     # @return lodel_id int: new lodel_id of the newly created LeObject
     def insert(self, letype, leclass, **datas):
         print("DummyDatasource.insert: ", letype, leclass, datas)
         return 42
 
     ## @brief delete an existing LeObject
-    # @param lodel_id int | (int): lodel_id of the object(s) to delete
-    # @param filters list : list of tuples formatted as (FIELD, OPERATOR, VALUE)
-    # @param relational_filters list
+    # @param letype LeType : LeType child class
+    # @param leclass LeClass : LeClass child class
+    # @param filters list : list of tuples formatted as (FIELD, OPERATOR, VALUE) (see @ref leobject_filters )
+    # @param relational_filters list : relationnal filters list (see @ref leobject_filters )
     # @return okay bool: True on success, it will raise on failure
-    def delete(self, lodel_id, filters, relational_filters):
+    def delete(self, letype, leclass, filters, relational_filters):
         print("DummyDatasource.delete: ", lodel_id)
         return True
 
     ## @brief search for a collection of objects
-    # @param emclass LeClass : LeClass instance
-    # @param emtype LeType : LeType instance
+    # @param leclass LeClass : LeClass instance
+    # @param letype LeType : LeType instance
     # @param field_list list : list of fields to get from the datasource
-    # @param filters list : list of tuples formatted as (FIELD, OPERATOR, VALUE)
-    # @param relational_filters list
+    # @param filters list : list of tuples formatted as (FIELD, OPERATOR, VALUE) (see @ref leobject_filters )
+    # @param relational_filters list : relationnal filters list (see @ref leobject_filters )
     # @return responses ({string:*}): a list of dict with field:value
-    def get(self, emclass, emtype, field_list, filters, relational_filters):
+    def get(self, leclass, letype, field_list, filters, relational_filters):
         print("DummyDatasource.get: ", emclass, emtype, field_list, filters, relational_filters)
         return []

leobject/leobject.py

@@ -16,6 +16,9 @@ import leobject
 import EditorialModel
 from EditorialModel.types import EmType
 
+REL_SUP = 0
+REL_SUB = 1
+
 ## @brief Main class to handle objects defined by the types of an Editorial Model
 class _LeObject(object):
     
@@ -95,8 +98,8 @@ class _LeObject(object):
         return okay
 
     ## @brief make a search to retrieve a collection of LeObject
-    # @param query_filters list : list of string of query filters (or tuple (FIELD, OPERATOR, VALUE) )
-    # @param field_list list|None : list of string representing fields
+    # @param query_filters list : list of string of query filters (or tuple (FIELD, OPERATOR, VALUE) ) see @ref leobject_filters
+    # @param field_list list|None : list of string representing fields see @ref leobject_filters
     # @param typename str : The name of the LeType we want
     # @param classname str : The name of the LeClass we want
     # @return responses ({string:*}): a list of dict with field:value
@@ -176,6 +179,8 @@ class _LeObject(object):
     # @throw LeObjectQueryError if their is some problems
     # @throw AttributeError if letype is not from the leclass class
     # @todo Delete the checks of letype and leclass and ensure that this method is called with letype and leclass arguments from _prepare_targets()
+    #
+    # @see @ref leobject_filters
     @staticmethod
     def _check_fields(letype, leclass, fields):
         #Checking that fields in the query_filters are correct
@@ -210,7 +215,9 @@ class _LeObject(object):
     # @param filters_l list : This list can contain str "FIELDNAME OP VALUE" and tuples (FIELDNAME, OP, VALUE)
     # @param letype LeType|None : needed to check filters
     # @param leclass LeClass|None : needed to check filters
-    # @return a tuple(FILTERS, RELATIONNAL_FILTERS°
+    # @return a tuple(FILTERS, RELATIONNAL_FILTERS
+    #
+    # @see @ref datasource_side
     @staticmethod
     def _prepare_filters(filters_l, letype = None, leclass = None):
         filters = list()
@@ -285,3 +292,46 @@ class LeObjectError(Exception):
 
 class LeObjectQueryError(LeObjectError):
     pass
+
+## @page leobject_filters LeObject query filters
+# The LeObject API provide methods that accept filters allowing the user
+# to query the database and fetch LodelEditorialObjects.
+#
+# The LeObject API translate those filters for the datasource. 
+# 
+# @section api_user_side API user side filters
+# Filters are string expressing a condition. The string composition
+# is as follow : "<FIELD> <OPERATOR> <VALUE>"
+# @subsection fpart FIELD
+# @subsubsection standart fields
+# Standart fields, represents a value of the LeObject for example "title", "lodel_id" etc.
+# @subsubsection rfields relationnal fields
+# relationnal fields, represents a relation with the object hierarchy. Those fields are composed as follow :
+# "<RELATION>.<NATURE>".
+#
+# - Relation can takes two values : superiors or subordinates
+# - Nature is a relation nature ( see EditorialModel.classtypes )
+# Examples : "superiors.parent", "subordinates.translation" etc.
+# @note The field_list arguement of leobject.leobject._LeObject.get() use the same syntax than the FIELD filter part 
+# @subsection oppart OPERATOR
+# The OPERATOR part of a filter is a comparison operator. There is
+# - standart comparison operators : = , <, > , <=, >=, !=
+# - list operators : 'in' and 'not in'
+# The list of allowed operators is sotred at leobject.leobject._LeObject._query_operators . 
+# @subsection valpart VALUE
+# The VALUE part of a filter is... just a value...
+#
+# @section datasource_side Datasource side filters
+# As said above the API "translate" filters before forwarding them to the datasource. 
+#
+# The translation process transform filters in tuple composed of 3 elements
+# ( @ref fpart , @ref oppart , @ref valpart ). Each element is a string.
+#
+# There is a special case for @ref rfields : the field element is a tuple composed with two elements
+# ( RELATION, NATURE ) where NATURE is a string ( see EditorialModel.classtypes ) and RELATION is one of
+# the defined constant : 
+#
+# - leobject.leobject.REL_SUB for "subordinates"
+# - leobject.leobject.REL_SUP for "superiors"
+#
+# @note The filters translation process also check if given field are valids compared to the concerned letype and/or the leclass