Changeset 2

Show
Ignore:
Timestamp:
11/13/08 12:33:47 (8 weeks ago)
Author:
fporcari
Message:

bellissimo

Location:
gnrpy
Files:
2 modified

Legend:

Unmodified
Added
Removed

  • gnrpy/gnr/core/gnrbag.py

    r1 r2  
    2222 
    2323""" 
    24  
    2524The gnrbag module contains a single class intended to be used: Bag 
    26  
    2725A Bag is a generic container object, similar to a dictionary, 
    2826with some useful properties: 
    29     - ordered 
    30     - accessible by key 
    31     - iterable 
    32     - hierarchical     
     27    
     28- ordered 
     29- accessible by key 
     30- iterable 
     31- hierarchical     
    3332     
    3433A Bag can store any kind of python object with a label in an ordered list. 
    … …  
    3736 
    3837A Bag can be loaded and saved in some ways: 
    39     - saved to and loaded from pikle files or strings:  
    40         the object stored in the bag must be picklable of course. 
    41     - saved to and loaded from xml files or strings with a specific syntax:  
    42         the object stored in the bag must be strings, numbers or dates. 
    43     - loaded from a generic xml file preserving the whole hierarchical structure and  
    44       the attributes: all values will be of type string of course. 
    45     - loaded from a generic html file: requires tidy. 
     38- saved to and loaded from pikle files or strings:  
     39the object stored in the bag must be picklable of course. 
     40- saved to and loaded from xml files or strings with a specific syntax:  
     41the object stored in the bag must be strings, numbers or dates. 
     42- loaded from a generic xml file preserving the whole hierarchical structure and  
     43the attributes: all values will be of type string of course. 
     44- loaded from a generic html file: requires tidy. 
    4645     
    4746Another class you could have to deal with is BagNode: they are Bag elements,  
    … …  
    8887    """ 
    8988    BagNode is the element type which a Bag is composed of. That's why it's 
    90     possible to say that a Bag is a collection of BagNodes. A BagNode is an object 
    91     that gather within itself, three main things: 
     89    possible to say that a Bag is a collection of BagNodes. A BagNode is an  
     90    object that gather within itself, three main things: 
     91     
    9292        -label: can be only a string. 
    9393        -value: can be anything, but a BagNode. Often value is a Bag. 
    9494        -attributes: dictionary that contains node's metadata    
     95         
    9596    """ 
    96     def __init__(self, parentbag, label, value=None, attr=None, resolver=None, validators=None,_removeNullAttributes=True): 
    97         """ 
    98         @param parentbag: Bag than contains the node 
    99         @param label: label that identifies the node 
    100         @param value: value of the node 
    101         @param attr: node's attributes 
    102         @param resolver: a BagResolver 
    103         @param validators: a dict with all validators pairs 
     97    def __init__(self, parentbag, label, value=None, attr=None, resolver=None, 
     98                validators=None,_removeNullAttributes=True): 
     99        """ 
     100        * `parentbag`: Bag than contains the node 
     101        * `label`: label that identifies the node 
     102        * `value`: value of the node 
     103        * `attr`: node's attributes 
     104        * `resolver`: a BagResolver 
     105        * `validators`: a dict with all validators pairs 
    104106        """ 
    105107        self.label = label 
    … …  
    112114        self.attr = {} 
    113115        if attr: 
    114             self.setAttr(attr, trigger = False,_removeNullAttributes=_removeNullAttributes) 
     116            self.setAttr(attr, trigger = False, 
     117                        _removeNullAttributes = _removeNullAttributes) 
    115118        if validators: 
    116119            self.setValidators(validators) 
    … …  
    169172        Returns the value of the BagNode. 
    170173        This method is called by the property .value 
    171         @param mode: can be one or more of: 
    172                     - static: to get the resolver instance instead of the calculated value 
    173                     - weak: to get a weak ref stored in the node instead of the actual object 
    174         @return: node's value 
     174         
     175        * `mode`: can be one or more of: 
     176                    - static: to get the resolver instance instead of the  
     177                              calculated value 
     178                    - weak: to get a weak ref stored in the node instead of  
     179                            the actual object 
     180                     
     181        Return: node's value 
    175182        """ 
    176183        if not self._resolver == None: 
    … …  
    187194        return self._value 
    188195     
    189     def setValue(self, value, trigger=True, _attributes=None, _updattr=None,_removeNullAttributes=True): 
     196    def setValue(self, value, trigger=True, _attributes = None, 
     197                _updattr = None,_removeNullAttributes = True): 
    190198        """ 
    191199        Set the node's value, unless the node is locked. 
    192200        This method is called by the property .value 
    193         @param value: the value to set the new bag inherits the trigger of the 
    194          parentbag and calls it sending an update event 
     201         
     202        * `value`: the value to set the new bag inherits the trigger of the 
     203                   parentbag and calls it sending an update event 
    195204        """ 
    196205        if self.locked: 
    … …  
    214223        if _attributes != None: 
    215224            evt='upd_value_attr' 
    216             self.setAttr(_attributes, trigger=False, _updattr=_updattr,_removeNullAttributes=_removeNullAttributes) 
     225            self.setAttr(_attributes, trigger = False, _updattr = _updattr, 
     226                        _removeNullAttributes=_removeNullAttributes) 
    217227        if trigger: 
    218228            for subscriber in self._node_subscribers.values(): 
    … …  
    222232                value.setBackRef(node=self,parent=self.parentbag) 
    223233            if trigger: 
    224                 self.parentbag._onNodeChanged(self, [self.label], oldvalue=oldvalue, evt=evt ) 
     234                self.parentbag._onNodeChanged(self, [self.label],  
     235                                              oldvalue=oldvalue, evt=evt) 
    225236 
    226237    value = property(getValue,setValue) 
    … …  
    262273        this method returns the value of an attribute given it's label. 
    263274        If it doesn't exists returns a default value. 
    264         @param label: the label of the attribute to get. 
     275        * `label`: the label of the attribute to get. 
    265276        """ 
    266277        if label: return self.attr.get(label,default) 
    … …  
    283294        return True 
    284295         
    285     def setAttr(self, attr=None, trigger=True, _updattr=True, _removeNullAttributes=True,**kwargs): 
     296    def setAttr(self, attr = None, trigger = True, _updattr = True,  
     297                _removeNullAttributes = True,**kwargs): 
    286298        """this method receives one or more key-value couple, passed as a dict or 
    287299        as named parameters, and sets them as attributes of the node 
    288         @param attr the dict of attributes to set into the node. 
     300         
     301        * `attr`: the dict of attributes to set into the node. 
     302         
    289303        """ 
    290304        if not _updattr: 
    … …  
    334348        If there are no validators into the node then addValidator instantiate 
    335349        a new BagValidationList and append the validator to it. 
    336         @param validator: the type of validation to set into the list of the node. 
    337         @param paremeterString: the parameters for a single validation type. 
     350        * `validator`: the type of validation to set into the list of the node. 
     351        * `paremeterString`: the parameters for a single validation type. 
    338352        """ 
    339353        if self._validators is None: 
    … …  
    460474        The "in" operator can be used to test the existence of a key in a 
    461475        bag. Also nested keys are allowed. 
    462         @param what: the key path to test. 
     476        * `what`: the key path to test. 
    463477        @return: a boolean value, True if the key exists in the bag, False otherwise. 
    464478         
    … …  
    485499        A path can also ba a list of keys. 
    486500         
    487         @param path: the item's path 
    488         @param default: an optional default value, default is 'None'.  
    489         @return: the value of the given item         
     501        * `path`: the item's path 
     502        * `default`: an optional default value, default is 'None'.  
     503         
     504        Return: the value of the given item         
    490505         
    491506        >>> mybag=Bag() 
    … …  
    592607        one step of the path, calling itself recursively. If autocreate mode is True, 
    593608        the method creates not existing nodes of the pathlist. 
    594         @param pathlist: list of nodes'labels 
     609        * `pathlist`: list of nodes'labels 
    595610        @return: current node's value 
    596611        """ 
    … …  
    690705        This method calls the __str__ method:  
    691706        asString() returns an ascii encoded formatted representation of the bag. 
    692         @param encoding: default is 'UTF-8' 
     707        * `encoding`: default is 'UTF-8' 
    693708        @return: a formatted representation of the bag contents (ascii) 
    694709         
    … …  
    735750        long as the Bag containing the requested values. 
    736751          
    737         @param what: this param is a comma separated string of special keys. 
    738                      Special keys are: 
     752        * `what`: this param is a comma separated string of special keys. 
     753                  Special keys are: 
     754                   
    739755                      - #k: the label of each node 
    740756                      - #v: the value of each node 
    … …  
    743759                      - #a.attrname: the attribute 'attrname' of each node 
    744760                      - subpath: the value of this subpath of each node 
    745                       this parameter can start with a path before the list of 
    746                       special keys to apply the digest to a subpath of this 
    747                       Bag. Path and special keys are separated by ':'. 
    748         @param condition: set a condition for digest process 
     761                                 this parameter can start with a path before the list of 
     762                                 special keys to apply the digest to a subpath of this 
     763                                 Bag. Path and special keys are separated by ':'. 
     764        * `condition`: set a condition for digest process 
    749765          
    750766        """ 
    … …  
    785801        """  
    786802        This method is analog to dictionary's has_key() method. 
    787         @param path: path of the given item. 
     803        * `path`: path of the given item. 
    788804        @return: a boolean value: True if the given item has a key, False otherwise. 
    789805         
    … …  
    810826        This method is analog to dictionary's pop() method. It pops the given item 
    811827        from the Bag; it returns the given item. 
    812         @param path: path of the given item. 
     828        * `path`: path of the given item. 
    813829        @return: the given item. 
    814830        """ 
    … …  
    843859        """ 
    844860        this method merge a Bag into the current one. 
    845         @param otherbag: a Bag to merge into. 
     861        * `otherbag`: a Bag to merge into. 
    846862        """ 
    847863        if isinstance(otherbag, basestring): 
    … …  
    934950        equal to 'value'. E.g. searching a node with a given 'id' in a Bag build from html. 
    935951         
    936         @param attr: path of the given item.  
    937         @param value: path of the given item.  
    938         @param path: optional, an empty list that will be filled with the path of the found node.  
    939         @return: a BagNode with the requested attribute""" 
     952        * `attr`: path of the given item.  
     953        * `value`: path of the given item.  
     954        * `path`: optional, an empty list that will be filled with the path of the found node.  
     955         
     956        Return: a BagNode with the requested attribute 
     957        """ 
    940958        bags=[] 
    941959        if path == None: path = [] 
    … …  
    957975        """ 
    958976        This method returns the BagNode stored at this path. 
    959         @param path: path of the given item.  
     977        * `path`: path of the given item.  
    960978        """ 
    961979        if not path: 
    … …  
    9911009        """ 
    9921010        This method set attributes into the node at the given path 
    993         @param _path: path of the target item.  
    994         @param _attributes:a dict of attributes to set into the node. 
     1011        * `_path`: path of the target item.  
     1012        * `_attributes`:a dict of attributes to set into the node. 
    9951013         
    9961014        """ 
    … …  
    10001018        """ 
    10011019        This method get the value of the attribute of the node at the given path 
    1002         @param path: path of the given item.  
    1003         @param _atts: the label of the attribute to get.  
     1020        * `path`: path of the given item.  
     1021        * `_atts`: the label of the attribute to get.  
    10041022        """ 
    10051023        node =  self.getNode(path) 
    … …  
    10151033        """This method splits a path string it at each '.' and returns a list of 
    10161034        nodes' labels and the label of the first list's element. 
    1017         @param path: the given path. 
     1035        * `path`: the given path. 
    10181036        @return label: the first label 
    10191037        @return pathlist: the list result of path splitting. 
    … …  
    10541072        If the path already exists, this method replicates the path keeping old 
    10551073        values and the new value. 
    1056         @param item_path: the path of the given item. 
    1057         @param item_value: the value to set. 
    1058         @param _attributes: an optional parameter, it specifies the attributes 
    1059          of the value to set. Default is 'None'. 
    1060         @param _position: specifies the position where to add the new item. 
    1061          It can be "<" or ">" followed by "#n" or "label". Default is append 
    1062          after last item. 
    1063         @return: the current bag. 
     1074        Parameters: 
     1075         
     1076        * item_path: the path of the given item. 
     1077        * item_value: the value to set. 
     1078        * _attributes: an optional parameter, it specifies the attributes 
     1079          of the value to set. Default is 'None'. 
     1080        * _position: specifies the position where to add the new item. 
     1081          It can be "<" or ">" followed by "#n" or "label". Default is append 
     1082          after last item. 
     1083         
     1084        Return:the current bag. 
    10641085         
    10651086        """ 
    … …  
    10741095        in the form "label1.label2...labelN".It returns the current bag. 
    10751096        If the path already exists, it overwrites the value at the given path. 
    1076         @param item_path: the path of the given item. 
    1077         @param item_value: the value to set. 
    1078         @param _attributes: an optional parameter, it specified the attributes of 
    1079          the value to set. Default is 'None'. 
    1080         @param _position: an optional parameter, if specified the method setItem() 
    1081          behaves like addItem(). Default is 'None'. 
    1082         @param _duplicate: specifies if a node with an existing path overwrite 
    1083         the value or append it. 
    1084         @param _validators: an optional parameter, it specified the validarors of 
    1085          the value to set. Default is 'None'. 
    1086         @param kwargs: all remaining kwargs can be attributes AND/OR validators . 
    1087         @return: the current bag. 
     1097        Parameters: 
     1098         
     1099        * `item_path`: the path of the given item. 
     1100        * `item_value`: the value to set. 
     1101        * `_attributes`: an optional parameter, it specified the attributes of 
     1102                         the value to set. Default is 'None'. 
     1103        * `_position`: an optional parameter, if specified the method setItem() 
     1104                       behaves like addItem(). Default is 'None'. 
     1105        * `_duplicate`: specifies if a node with an existing path overwrite 
     1106                        the value or append it. 
     1107        * `_validators`: an optional parameter, it specified the validarors of 
     1108                         the value to set. Default is 'None'. 
     1109        * `kwargs`: all remaining kwargs can be attributes AND/OR validators . 
     1110         
     1111        Return: the current bag. 
    10881112        """ 
    10891113 
    … …  
    11101134            obj, label = self._htraverse(item_path, autocreate=True) 
    11111135            obj._set(label, item_value, _attributes=_attributes, _position=_position, 
    1112                            _duplicate=_duplicate, _updattr=_updattr,_validators = _validators,_removeNullAttributes=_removeNullAttributes) 
     1136                           _duplicate=_duplicate, _updattr=_updattr, 
     1137                           _validators = _validators,_removeNullAttributes=_removeNullAttributes) 
    11131138    __setitem__ = setItem 
    11141139     
    1115     def _set(self, label, value, _attributes=None, _position=None, _duplicate=False, _updattr=False, _validators=None,_removeNullAttributes=True): 
     1140    def _set(self, label, value, _attributes=None, _position=None,  
     1141            _duplicate=False, _updattr=False, _validators=None,_removeNullAttributes=True): 
    11161142        resolver = None 
    11171143        if isinstance(value, BagResolver): 
    … …  
    11251151                raise BagException ('Not existing index in #n syntax') 
    11261152            else: 
    1127                 self._insertNode(BagNode(self,label=label,value=value,attr=_attributes,resolver=resolver, validators=_validators,_removeNullAttributes=_removeNullAttributes), _position) 
     1153                self._insertNode(BagNode(self,label=label,value=value,attr=_attributes, 
     1154                                resolver=resolver, validators=_validators, 
     1155                                _removeNullAttributes=_removeNullAttributes), _position) 
    11281156        else: 
    11291157            node=self._nodes[i] 
    … …  
    11321160            if _validators: 
    11331161                node.setValidators(_validators) 
    1134             node.setValue(value, _attributes=_attributes, _updattr=_updattr,_removeNullAttributes=_removeNullAttributes) 
     1162            node.setValue(value, _attributes=_attributes, _updattr=_updattr, 
     1163                        _removeNullAttributes=_removeNullAttributes) 
    11351164    def defineSymbol(self,**kwargs): 
    11361165        """ 
    11371166        Define a variable and link it to a value at the specified path. The value 
    11381167        linked is a BagFormula Resolver. 
    1139         @param kwargs: a dict of symbol to define for a formula. 
     1168        * `kwargs`: a dict of symbol to define for a formula. 
    11401169        """ 
    11411170        if self._symbols == None: 
    … …  
    11461175        """ 
    11471176        Define a formula that uses defined symbols. 
    1148         @param kwargs: a pair of key-value which rapresent the formula and the 
     1177        * `kwargs`: a pair of key-value which rapresent the formula and the 
    11491178        string that describes it. 
    11501179        """ 
    … …  
    11571186        """ 
    11581187        Sets a BagFormula resolver. 
    1159         @param formula: a string that represents the expression with symbolic vars 
    1160         @param kwargs: links between symbols and paths associated to their values 
     1188        * `formula`: a string that represents the expression with symbolic vars 
     1189        * `kwargs`: links between symbols and paths associated to their values 
    11611190        """ 
    11621191        self.setBackRef() 
    … …  
    11711200        """ 
    11721201        This method get the resolver of the node at the given path. 
    1173         @param path: path of the node. 
     1202        * `path`: path of the node. 
    11741203        """ 
    11751204        return self.getNode(path).getResolver() 
    … …  
    11791208        """ 
    11801209         This method set a resolver into the node at the given path. 
    1181          @param path: path of the node. 
     1210         * `path`: path of the node. 
    11821211         """    
    11831212        return self.setItem(path,None,resolver=resolver) 
    … …  
    11891218         and it knows has a reference to its Parent. 
    11901219          
    1191          @param node: not required 
    1192          @param parent: not required 
     1220         * `node`: not required 
     1221         * `parent`: not required 
    11931222         """ 
    11941223        if self.backref != True: 
    … …  
    12861315        If the label doesn't exist it returns -1.  
    12871316        The mach is not case sensitive. 
    1288         @param label: a not hierarchical label. 
     1317        * `label`: a not hierarchical label. 
    12891318        @return: position into the bag. 
    12901319         
    … …  
    13241353        """ 
    13251354        This method returns a pickled Bag. 
    1326         @param destination: an optional parameter; it is the destination path; 
    1327          default is 'None'. 
    1328         @param bin: a boolean optional parameter, if set to 'False' the Bag is 
    1329          pickled in ASCII code, if set to 'True' is pickled in binary format. 
    1330          Default is 'True'. 
    1331         @return: the pickled Bag. 
     1355         
     1356        * `destination`: an optional parameter; it is the destination path; 
     1357                         default is 'None'. 
     1358        * `bin`: a boolean optional parameter, if set to 'False' the Bag is 
     1359                 pickled in ASCII code, if set to 'True' is pickled in binary format. 
     1360                 Default is 'True'. 
     1361          
     1362        Return: the pickled Bag. 
    13321363         
    13331364        """ 
    … …  
    13461377        """ 
    13471378        This method unpickles a pickled Bag. 
    1348         @param source: the source path. 
     1379        * `source`: the source path. 
    13491380        @return: the unpickled Bag. 
    13501381         
    … …  
    13711402#-------------------- toXml -------------------------------- 
    13721403    def toXml(self,filename=None,encoding='UTF-8',typeattrs=True, unresolved=False,  
    1373               autocreate=False, jsonmode=None, jsonkey=None, translate_cb=None, omitUnknownTypes=False, catalog=None): 
     1404              autocreate=False, jsonmode=None, jsonkey=None, translate_cb=None,  
     1405              omitUnknownTypes=False, catalog=None): 
    13741406        """ 
    13751407        This method returns a complete standard XML version of the Bag, 
    … …  
    13801412        Is also possible to write the result on a file, passing the path of the file 
    13811413        as the 'filename' parameter. 
    1382         @param filename: an optional parameter, it is the path of the output file; 
    1383          default value is 'None' 
    1384         @param encoding: an optional parameter, is used to set the XML encoding; 
    1385          default value is UTF-8. 
    1386         @return: an XML version of the bag. 
     1414         
     1415        * `filename`: an optional parameter, it is the path of the output file; 
     1416                      default value is 'None' 
     1417        * `encoding`: an optional parameter, is used to set the XML encoding; 
     1418                      default value is UTF-8. 
     1419          
     1420        Return: an XML version of the bag. 
    13871421         
    13881422            >>> mybag=Bag() 
    … …  
    14041438        This method fills a void Bag from: basestring, bag, list. 
    14051439         
    1406         @param source: the source for the Bag. 
     1440        * `source`: the source for the Bag. 
    14071441                       
    14081442        """ 
    … …  
    14311465    def _fromSource(self, source, fromFile, mode): 
    14321466        """ 
    1433         @param source: the source string or source URI 
    1434         @param fromFile: flag that says if source is eventually an URI 
    1435         @param mode: flag that means the importation mode (XML, pickle or VCARD) 
     1467        * `source`: the source string or source URI 
     1468        * `fromFile`: flag that says if source is eventually an URI 
     1469        * `mode`: flag that means the importation mode (XML, pickle or VCARD) 
    14361470        @return: a bag from unpickle or from fromXml 
    14371471         
    … …  
    14601494        """ 
    14611495        Generate a Bag from a generic xml 
    1462         @param source: an xml string or a path to an xml document. 
     1496        * `source`: an xml string or a path to an xml document. 
    14631497        @type source: basestring 
    14641498        @return: source, fromFile, mode 
    … …  
    15131547        """ 
    15141548        This method fills the Bag with values read from an XML string or file or URL. 
    1515         @param source: the XML source to be loaded in the Bag.  
    1516         @param catalog: 
    1517         @param bagcls: 
     1549        * `source`: the XML source to be loaded in the Bag.  
     1550        * `catalog`: 
     1551        * `bagcls`: 
    15181552        bagcls empty: 
    15191553        """ 
    … …  
    15591593        """ 
    15601594        This method add a validator into the node at the given path 
    1561         @param path: path of the node. 
    1562         @param validator: the type of validation. 
    1563         @param parameterString: string which contains the params for validation. 
     1595        * `path`: path of the node. 
     1596        * `validator`: the type of validation. 
     1597        * `parameterString`: string which contains the params for validation. 
    15641598        """ 
    15651599        self.getNode(path,autocreate=True).addValidator(validator, parameterString) 
    … …  
    16141648        this means that I can define many eventhandlers for the same event. 
    16151649         
    1616         @param subscriberId: an ID can be assigned for a subscription 
    1617         @param update: the eventhandler function linked to update event. 
    1618         @param insert: the eventhandler function linked to insert event. 
    1619         @param delete: the eventhandler function linked to delete event. 
    1620         @param any: the eventhandler function linked to do whenever something happens. 
     1650        * `subscriberId`: an ID can be assigned for a subscription 
     1651        * `update`: the eventhandler function linked to update event. 
     1652        * `insert`: the eventhandler function linked to insert event. 
     1653        * `delete`: the eventhandler function linked to delete event. 
     1654        * `any`: the eventhandler function linked to do whenever something happens. 
    16211655        """ 
    16221656        if self.backref == False: 
    … …  
    16311665        delete a subscription of an event of given subscriberId. 
    16321666         
    1633         @param subscriberId: an ID can be assigned for a subscription 
    1634         @param update: the eventhandler function to remove 
    1635         @param insert: the eventhandler function to remove 
    1636         @param delete: the eventhandler function to remove 
    1637         @param any: the eventhandler function to remove 
     1667        * `subscriberId`: an ID can be assigned for a subscription 
     1668        * `update`: the eventhandler function to remove 
     1669        * `insert`: the eventhandler function to remove 
     1670        * `delete`: the eventhandler function to remove 
     1671        * `any`: the eventhandler function to remove 
    16381672         
    16391673        """ 
    … …  
    16721706        """ 
    16731707        Calls a function for each node of the Bag. 
    1674         @param callback: the function which is called. 
     1708        * `callback`: the function which is called. 
    16751709        """ 
    16761710        result=None 
    … …  
    17001734    def