Documentation on the lodel.leapi.datahandlers.datas module

lodel/editorial_model/translator/__init__.py

@@ -1,4 +1,4 @@
 ## @package lodel.editorial_model.translator Editorial model translators
 #
-# This package is dedicated to the translation of an EditorialModel as several formats like pickle files or XML files.
+# This package is dedicated to the translation of an EditorialModel as several formats like pickle files or XML files. \n
 # Each module provides save and load functions to read/write an lodel.editorial_model.model.EditorialModel object from and to a file.

lodel/leapi/datahandlers/datas.py

@@ -1,4 +1,9 @@
 #-*- coding: utf-8 -*-
+
+## @package lodel.leapi.datahandlers.datas
+# This module contains specific datahandlers extending the basic ones from the lodel.leapi.datahandlers.datas_base module.
+
+
 import warnings
 import inspect
 import re
@@ -12,22 +17,29 @@ LodelContext.expose_modules(globals(), {
                          'LodelFatalError', 'DataNoneValid', 'FieldValidationError']})
 
 
-##@brief Data field designed to handle formated strings
+## @brief Data field designed to handle formated strings
 class FormatString(Varchar):
 
-    help = 'Automatic string field, designed to use the str % operator to \
-build its content'
+    help = 'Automatic string field, designed to use the str % operator to build its content'
     base_type = 'char'
     
-    ##@brief Build its content with a field list and a format string
-    # @param format_string str
-    # @param field_list list : List of field to use
-    # @param **kwargs
+    ## @brief Constructor
+    # @param _field_list list : List of fields to use
+    # @param _format_string str : formatted string
+    # @param **kwargs : additional options
     def __init__(self, format_string, field_list, **kwargs):
         self._field_list = field_list
         self._format_string = format_string
         super().__init__(internal='automatic', **kwargs)
 
+    ## @brief constructs the formatted string data
+    # The string can be truncated depending on the maximum length defined for this field.
+    #
+    # @param emcomponent EmComponent
+    # @param fname str
+    # @param datas dict
+    # @param cur_value str
+    # @return str
     def _construct_data(self, emcomponent, fname, datas, cur_value):
         ret = self._format_string % tuple(
             datas[fname] for fname in self._field_list)
@@ -35,27 +47,28 @@ build its content'
             warnings.warn("Format field overflow. Truncating value")
             ret = ret[:self.max_length]
         return ret
-    
-##@brief Varchar validated by a regex
+
+
+## @brief Varchar validated by a regex
 class Regex(Varchar):
 
     help = 'String field validated with a regex. Takes two options : \
 max_length and regex'
     base_type = 'char'
 
-    ##@brief A string field validated by a regex
-    # @param regex str : a regex string (passed as argument to re.compile())
+    ## @brief A string field validated by a regex
+    # @param regex str : a regex string (passed as argument to re.compile()), default value is an empty string
     # @param max_length int : the max length for this field (default : 10)
-    # @param **kwargs
+    # @param **kwargs : additional options
     def __init__(self, regex='', max_length=10, **kwargs):
         self.regex = regex
         self.compiled_re = re.compile(regex)  # trigger an error if invalid regex
         super(self.__class__, self).__init__(max_length=max_length, **kwargs)
 
-    ##@brief Check and cast value in appropriate type
-    #@param value *
-    #@throw FieldValidationError if value is unappropriate or can not be cast 
-    #@return value
+    ## @brief Check and cast value in appropriate type
+    # @param value *
+    # @throw FieldValidationError if value is unappropriate or can not be cast
+    # @return str
     def _check_data_value(self, value):
         value = super()._check_data_value(value)
         if not self.compiled_re.match(value) or len(value) > self.max_length:
@@ -63,6 +76,10 @@ max_length and regex'
             raise FieldValidationError(msg)
         return value
 
+    ## @brief checks if another datahandler can override this one
+    #
+    # @param data_handler Datahandler
+    # @return bool
     def can_override(self, data_handler):
         if not super().can_override(data_handler):
             return False
@@ -71,36 +88,58 @@ max_length and regex'
             return False
         return True
 
+
 ##@brief Handles uniq ID
 class UniqID(Integer):
 
     help = 'Fieldtype designed to handle editorial model UID'
     base_type = 'int'
 
-    ##@brief A uid field
-    # @param **kwargs
+    ## @brief A uid field
+    #
+    # @param **kwargs dict
     def __init__(self, **kwargs):
         kwargs['internal'] = 'automatic'
         super(self.__class__, self).__init__(primary_key = True, **kwargs)
 
+    ## @brief Constructs the field's data
+    # @param emcomponent EmComponent : Component corresponding to the field
+    # @param fname
+    # @param datas
+    # @param cur_value str : current value to use (is retrieved from the datasource if not given)
+    # @return str
+    # @remarks fname and datas are not used and should become non mandatory, cur_value should have a None default value
     def construct_data(self, emcomponent, fname, datas, cur_value):
         if cur_value is None:
             #Ask datasource to provide a new uniqID
             return emcomponent._ro_datasource.new_numeric_id(emcomponent)
         return cur_value
 
+
+## @brief Class representing a LeObject subclass
 class LeobjectSubclassIdentifier(Varchar):
     
     help = 'Datahandler designed to handle LeObject subclass identifier in DB'
     base_type = 'varchar'
 
+    ## @brief Constructor
+    # @param kwargs dict : additional options
+    # @throw RuntimeError
+    # @todo define the "internal" option that can be given in the kwargs, and document its meaning
     def __init__(self, **kwargs):
         if 'internal' in kwargs and not kwargs['internal']:
             raise RuntimeError(self.__class__.__name__+" datahandler can only \
 be internal")
         kwargs['internal'] = True
         super().__init__(**kwargs)
-    
+
+    ## @brief Returns the class' name
+    # @param emcomponent EmComponent : Component correponding to the field
+    # @param fname
+    # @param datas
+    # @param cur_value
+    # @return str
+    # @remarks fname, datas and cur_value should be given default values as they are not mandatory here.
     def construct_data(self, emcomponent, fname, datas, cur_value):
         cls = emcomponent
         if not inspect.isclass(emcomponent):
@@ -108,13 +147,13 @@ be internal")
         return cls.__name__
 
 
-##@brief Data field designed to handle concatenated fields
+## @brief Data field designed to handle concatenated fields
 class Concat(FormatString):
     help = 'Automatic strings concatenation'
     base_type = 'char'
     
-    ##@brief Build its content with a field list and a separator
-    # @param field_list list : List of field to use
+    ## @brief Build its content with a field list and a separator
+    # @param field_list list : List of fields to concatenate
     # @param separator str
     # @param **kwargs    
     def __init__(self, field_list, separator=' ', **kwargs):
@@ -124,22 +163,34 @@ class Concat(FormatString):
                          **kwargs)
 
 
+## @brief Datahandler managing a password
 class Password(Varchar):
     help = 'Handle passwords'
     base_type = 'password'
     pass
 
-
+## @brief Datahandler turning a string into a list
 class VarcharList(Varchar):
     help = 'DataHandler designed to make a list out of a string.'
     base_type = 'varchar'
-    
+
+    ## @brief Constructor
+    # @param delimiter str : default value is a whitespace character
+    # @param **kwargs : additional options
+    # @throw LodelException : this exception is raised when the delimiter is not a string
     def __init__(self, delimiter=' ', **kwargs):
         if not isinstance(delimiter, str):
             raise LodelException("The delimiter has to be a string, %s given" % type(delimiter))
         self.delimiter = str(delimiter)
         super().__init__(**kwargs)
 
+    ## @brief Constructs the field's data
+    # @param emcomponent EmComponent
+    # @param fname
+    # @param datas
+    # @param cur_value : current value to use
+    # @return list
+    # @remarks emcomponent, fname and datas should be given a default value as they seem to be non mandatory
     def construct_data(self, emcomponent, fname, datas, cur_value):
         result = cur_value.split(self.delimiter)
         return result