Changeset 464

Show
Ignore:
Timestamp:
09/03/10 23:54:08 (21 months ago)
Author:
emuller
Message:

Fixups to docstrings

Location:
branches/parameter_set_schema_validation
Files:
3 modified

Legend:

Unmodified
Added
Removed

  • branches/parameter_set_schema_validation/src/parameters/__init__.py

    r456 r464  
    1414ParameterSpace  - a collection of ParameterSets, representing multiple points in 
    1515                  parameter space. 
    16 ParameterSchema - a sub-class of ParameterSet, which may also contain  
     16 
     17**Imported from NeuroTools.parameters.validators** 
     18 
     19ParameterSchema      - A sub-class of ParameterSet against which other ParameterSets can be validated 
     20                       against using a Validator as found in the sub-package 
     21                       NeuroTools.parameters.validators  
     22 
     23CongruencyValidator  - A CongruencyValidator validates a ParameterSet against a ParameterSchema 
     24                       via member "validate(parameter_set,parameter_schema)". 
     25 
     26ValidationError      - The Exception raised when validation fails 
     27 
     28SchemaBase           - The base class of all "active" Schema objects to be placed in a ParameterSchema. 
     29-> Sublass           - Validates the same-path ParameterSet value if it is of the specified type. 
     30-> Eval              - Validates the same-path ParameterSet value if the provided expression 
     31                       evaluates ("eval") to True. 
    1732 
    1833 
    … …  
    2439nesteddictflatten - Return a flattened version of a nested dict structure. 
    2540string_table      - Convert a table written as a multi-line string into a dict of dicts. 
     41 
     42 
     43 
     44Sub-Packages 
     45------------ 
     46 
     47validators        - A module implementing validation of ParameterSets against ParameterSchema. 
    2648 
    2749""" 

  • branches/parameter_set_schema_validation/src/parameters/validators.py

    r456 r464  
     1""" 
     2NeuroTools.parameters.validators 
     3================================ 
     4 
     5A module implementing validation of ParameterSets against ParameterSchema. 
     6 
     7Classes 
     8------- 
     9 
     10SchemaBase           - The base class of all "active" Schema objects to be placed in a ParameterSchema. 
     11-> Sublass           - Validates the same-path ParameterSet value if it is of the specified type. 
     12-> Eval              - Validates the same-path ParameterSet value if the provided expression 
     13                       evaluates ("eval") to True. 
     14 
     15ParameterSchema      - A sub-class of ParameterSet against which other ParameterSets 
     16                       can be validated against. 
     17 
     18CongruencyValidator  - A CongruencyValidator validates a ParameterSet against a ParameterSchema 
     19                       via member "validate(parameter_set,parameter_schema)". 
     20 
     21ValidationError      - The Exception raised when validation fails 
     22 
     23Functions 
     24--------- 
     25 
     26congruent_dicts      - returns True if two nested dictionaries have the same key heirarchy, 
     27                       otherwise False. 
     28 
     29 
     30See also: NeuroTools.parameters 
     31 
     32""" 
     33 
     34 
    135import yaml 
    236from NeuroTools.parameters import ParameterSet 
    … …  
    640 
    741class SchemaBase(object): 
    8      
     42    """ The base class of all "active" Schema objects to be placed in a ParameterSchema. 
     43 
     44    Schema objects define the "validate" member which accepts the to-be-validated ParameterSet 
     45    value from the same path as the Schema object in the ParameterSchema and returns True if 
     46    the value is valid, otherwise False. 
     47 
     48    """ 
     49 
    950    def __init__(self): 
    1051        pass 
    … …  
    1960 
    2061class Subclass(SchemaBase): 
     62    """ 
     63    To be used as a value in a ParameterSchema.  Validates the same-path 
     64    ParameterSet value if it is of the specified type. 
     65 
     66    See also: SchemaBase 
     67    """ 
    2168     
    2269    def __init__(self, type=None): 
    … …  
    3178 
    3279    def __eq__(self,x): 
    33         return self.type == x.type 
     80        if isinstance(x,Subclass): 
     81            return self.type == x.type 
     82        else: 
     83            return False 
     84 
     85class Eval(SchemaBase): 
     86    """ 
     87    To be used as a value in a ParameterSchema.  Validates the same-path 
     88    ParameterSet value if the provided expression (with leaf(value) mapped to var in eval local namespace) 
     89    evaluates to True. 
     90 
     91    See also: SchemaBase 
     92    """ 
     93 
     94     
     95    def __init__(self, expr, var='leaf'): 
     96        self.var = var 
     97        self.expr = expr 
     98 
     99    def validate(self, leaf): 
     100        l = {} 
     101        l[self.var] = leaf 
     102        return eval(self.expr,{},l) 
     103 
     104    def __repr__(self): 
     105        cls = self.__class__ 
     106        return '.'.join([cls.__module__,cls.__name__])+'(%s,var=%s)' % (self.expr,self.var) 
     107 
     108    def __eq__(self,x): 
     109        if isinstance(x,Eval): 
     110            return self.expr == x.expr and self.var == x.var 
     111        else: 
     112            return False 
     113 
    34114 
    35115 
    36116# add all schema checkers to this list 
    37 schema_checkers = [Subclass] 
     117schema_checkers = [Subclass,Eval] 
    38118# create a namespace of schema_checkers 
    39119schema_checkers_namespace = {} 
    … …  
    43123class ParameterSchema(ParameterSet): 
    44124    """ 
    45     A sub-class of ParameterSet against which other ParameterSets can be validated against 
    46  
    47     Presenlty, it is more or less a ParameterSet, with all leafs which are not explicitly 
    48     a subclass of the BaseSchema object replaced by a SubclassSchema(type=<leaf type>) instance. 
    49  
    50     In the future a ParameterSchema may contain Schema objects which 
    51     validate leafs by a member function returning true or false if the given leaf in the 
    52     ParameterSet should be validated or not, eg: 
    53     LambdaSchema('x','isinstance(x,str)'), 
    54     TimedateSchema('%.2d-%.2m-%.2y'), etc. 
     125    A sub-class of ParameterSet against which other ParameterSets can be validated against. 
     126 
     127    Presenlty, it is more or less a ParameterSet, with all leafs(values) which are not explicitly 
     128    a subclass of the SchemaBase object replaced by a Subclass(type=<leaf(value) type>) instance. 
     129 
     130    ParameterSchema may contain arbitrary Schema objects subclassed from SchemaBase which 
     131    validate leafs by the member function "validate(leaf)" returning True or false if the given 
     132    leaf in the ParameterSet at the same path should be validated or not, eg: 
     133 
     134    LambdaSchema('isinstance(x,str)',var='x'), 
     135    *unimplemented* Timedate('%.2d-%.2m-%.2y'), etc. 
     136    *unimplemented* Email() 
     137    *unimplemented* Url() 
     138    *unimplemented* File() 
     139    *unimplemented* FileExists() 
     140     
     141    etc. 
    55142 
    56143    example: 
    57144 
    58     schema = ParameterSchema({'age': 0, 'height': Subclass(float)}) 
     145    >>> schema = ParameterSchema({'age': 0, 'height': Subclass(float)}) 
    59146    # is equivalent to  
    60     schema = ParameterSchema({'age': Subclass(int), 'height': Subclass(float)}) 
     147    >>> schema = ParameterSchema({'age': Subclass(int), 'height': Subclass(float)}) 
     148 
     149    See also: SchemaBase, Eval, Subclass 
    61150     
    62151    """ 
    … …  
    85174 
    86175class ValidationError(Exception): 
     176    """ Raised when ParameterSchema validation fails, and provides failure information 
     177 
     178    See also: CongruencyValidator, ParameterSchema 
     179 
     180    """ 
     181     
    87182    def __init__(self, path='',schema_base=None, parameter=None ): 
    88183        self.path = path 
    … …  
    115210        
    116211 
     212    See also: NeuroTools.parameters.ParameterSet, ParameterSchema 
     213 
    117214    """ 
    118215 
    … …  
    133230        and vice-versa, and will run validation for each item in the namespace tree. 
    134231 
    135         See als0: CongruencyValidator docstring. 
     232        See also: CongruencyValidator docstring. 
    136233 
    137234        """ 
    … …  
    219316NeuroTools.parameters.ParameterSchema = ParameterSchema 
    220317NeuroTools.parameters.Subclass = Subclass 
     318NeuroTools.parameters.Eval = Eval 
     319NeuroTools.parameters.SchemaBase = SchemaBase 
    221320NeuroTools.parameters.CongruencyValidator = CongruencyValidator 
    222321NeuroTools.parameters.ValidationError = ValidationError 

  • branches/parameter_set_schema_validation/test/test_validators.py

    r460 r464  
    6363        # is equivalent to  
    6464        s2 = ParameterSchema({'age': Subclass(int), 'height': Subclass(float)}) 
     65 
    6566         
    6667        assert s1 == s2 
    … …  
    7273        v = CongruencyValidator() 
    7374        assert v.validate(ps3,s1)==True 
    74          
     75 
     76    def test_eval(self): 
     77 
     78        s1 = ParameterSchema(ps3) 
     79 
     80        v = CongruencyValidator() 
     81        # test Eval which checks for isinstance(x,list) 
     82        s1.mylist = NeuroTools.parameters.validators.Eval('isinstance(x,list)',var='x') 
     83        assert v.validate(ps3,s1)==True 
     84 
     85        # test default var 'leaf' 
     86        s1.hello = NeuroTools.parameters.validators.Eval('isinstance(leaf,str)') 
     87        assert v.validate(ps3,s1)==True 
     88 
     89        # test failure and var as non-kwarg 
     90        s1.mylist = NeuroTools.parameters.validators.Eval('isinstance(x,str)','x') 
     91 
     92        r = False 
     93        try: 
     94            r = v.validate(ps3,s1) 
     95        except Exception as e: 
     96            assert isinstance(e,ValidationError) 
     97            assert e.path=='mylist' 
     98            assert e.parameter==ps3.mylist 
     99            assert e.schema_base==s1.mylist 
     100        assert r == False 
     101 
     102 
    75103    def test_simple_validate(self): 
    76104        v = CongruencyValidator()