gchecky.gxml.Field

Package gchecky :: Module gxml :: Class Field |
[hide private]
[frames] | no frames]

# Class Field

source code

    object --+
             |
            Field

Known Subclasses:
  String, Any, Boolean, Complex, Decimal, Double, Long, List, Timestamp

Holds all the meta-information about mapping the current field value into/from the xml DOM tree.

An instance of the class specifies the exact path to the DOM node/subnode/attribute that contains the field value. It also holds other field traits such as:

Instance Methods | [hide private]
__init__(self, path, **kwargs) Specify initial parameters for this field instance. | source code
get_initial_value(self) | source code
save(self, node, data) Save the field data value into the DOM node. | source code
load(self, node) Load the field data from the xml DOM node. | source code
validate(self, data) Validate data according to this fields parameters. | source code
data2str(self, data) Override this method in subclasses | source code
str2data(self, str) Override this method in subclasses | source code
create_node_for_path(self, parent, reuse_nodes=True) Create (if needed) a XML DOM node that will hold this field data. | source code
get_nodes_for_path(self, parent) Retrieve all the nodes that hold data supposed to be assigned to this field. | source code
get_one_node_for_path(self, parent) Same as 'get_nodes_path' but checks that there is exactly one result and returns it. | source code
get_any_node_for_path(self, parent) Same as 'get_nodes_path' but checks that there is no more than one result and returns it, or None if the list is empty. | source code
_traits(self) Return the string representing the field traits. | source code
__repr__(self) Used in documentation. | source code
Inherited from `object`: `__delattr__`, `__getattribute__`, `__hash__`, `__new__`, `__reduce__`, `__reduce_ex__`, `__setattr__`, `__str__`

Class Methods | [hide private]
deconstruct_path(cls, path) Deconstruct a path string into pieces suitable for xml DOM processing. | source code
reconstruct_path(cls, chunks, attribute) Reconstruct the path back into the original form using the deconstructed form. | source code

Instance Variables | [hide private]
| path = ``'````'`` the path to the xml DOM node/attribute to store the field data
| required = `True` required or optional
| empty = `False` weither the field value could be empty (an empty XML tag)
| default = `None` the default value for the field
| values = `None` the list of acceptable values
| save_node_and_xml = `False` a boolean that specifies if the original xml and DOM element should be saved.

Properties | [hide private]
Inherited from `object`: `__class__`

Method Details | [hide private]

### deconstruct_path(cls, path) Class Method | source code
  - Deconstruct a path string into pieces suitable for xml DOM processing. Parameters: `path` - a string in the form of /chunk1/chunk2/.../chunk_n/@attribute. It denotes a DOM node or an attibute which holds this fields value. This corresponds to an hierarchy of type:
         chunk1
          \- chunk2
             ...
              \- chunk_n
                  \- @attribute
Where chunk_n are DOM nodes and @attribute is a DOM attribute. Chunks and @attribute are optional. An empty string denotes the current DOM node. Returns: `(chunks, attribute)` - a list of chunks and attribute value (or None). See Also: reconstruct_path

### reconstruct_path(cls, chunks, attribute) Class Method | source code
Reconstruct the path back into the original form using the deconstructed form. A class method. Parameters: `chunks` - a list of DOM sub-nodes. `attribute` - a DOM attribute. Returns: a string path denoting the DOM node/attribute which should contain the field value. See Also: deconstruct_path

### __init__(self, path, **kwargs) (Constructor) | source code
Specify initial parameters for this field instance. The list of actual parameters depends on the subclass. Parameters: `path` - The path determines the DOM node/attribute to be used to store/retrieve the field data value. It will be directly passed to deconstruct_path. Overrides: object.__init__

### save(self, node, data) | source code
Save the field data value into the DOM node. The value is stored accordingly to the field path which could be the DOM node itself or its subnodes (which will be automatically created), or (a sub)node attribute. Parameters: `node` - The DOM node which (or subnodes of which) will contain the field data value. `data` - The data value for the field to be stored.

### load(self, node) | source code
Load the field data from the xml DOM node. The value is retrieved accordingly to the field path and other traits. Parameters: `node` - The xml NODE that (or subnodes or attribute of which) contains the field data value. @see save, __init__

### validate(self, data) | source code
    Validate data according to this fields parameters.

    @return True if data is ok, otherwise return a string (!) describing
            why the data is invalid.

    Note that this method returns either True or an error string, not False!

    The Field class considers any data as valid and returns True.

### create_node_for_path(self, parent, reuse_nodes=True) | source code
Create (if needed) a XML DOM node that will hold this field data. Parameters: `parent` - The parent node that should hold this fields data. `reuse_nodes` - Reuse the existing required node if it is already present. Returns: Return the XML DOM node to hold this field's data. The node created as a subnode (or an attribute, or a grand-node, etc.) of parent.

### get_nodes_for_path(self, parent) | source code
Retrieve all the nodes that hold data supposed to be assigned to this field. If this field path matches a subnode (or a 'grand' subnode, or an atribute, etc) of the 'parent' node, then it is included in the returned list. Parameters: `parent` - The node to scan for this field data occurences. Returns: The list of nodes that corresponds to this field.

### _traits(self) | source code
Return the string representing the field traits. See Also: __repr__

### __repr__(self) (Representation operator) | source code
Used in documentation. This method is called from subclasses __repr__ method to generate a human-readable description of the current field instance. Overrides: object.__repr__

Instance Variable Details | [hide private]

  ### save_node_and_xml a boolean that specifies if the original xml and DOM element should be saved. Handly for fields that could contain arbitrary data such as 'merchant-private-data' and 'merchant-private-item-data'. The original xml text is saved into <field>_xml. The corresponding DOM node is stored into <field>_dom. Value:
      False