Project

General

Profile

1
# XML "function" nodes that transform their contents
2

    
3
import datetime
4
import re
5
import sre_constants
6
import warnings
7

    
8
import angles
9
import dates
10
import exc
11
import format
12
import maps
13
import sql
14
import sql_io
15
import strings
16
import term
17
import units
18
import util
19
import xml_dom
20
import xpath
21

    
22
##### Exceptions
23

    
24
class SyntaxError(exc.ExceptionWithCause):
25
    def __init__(self, cause):
26
        exc.ExceptionWithCause.__init__(self, 'Invalid XML function syntax',
27
            cause)
28

    
29
class FormatException(exc.ExceptionWithCause):
30
    def __init__(self, cause):
31
        exc.ExceptionWithCause.__init__(self, 'Invalid input value', cause)
32

    
33
##### Helper functions
34

    
35
def map_items(func, items):
36
    return [(name, func(value)) for name, value in items]
37

    
38
def cast(type_, val):
39
    '''Throws FormatException if can't cast'''
40
    try: return type_(val)
41
    except ValueError, e: raise FormatException(e)
42

    
43
def conv_items(type_, items):
44
    return map_items(lambda val: cast(type_, val),
45
        xml_dom.TextEntryOnlyIter(items))
46

    
47
def pop_value(items, name='value'):
48
    '''@param name Name of value param, or None to accept any name'''
49
    try: last = items.pop() # last entry contains value
50
    except IndexError: return None # input is empty and no actions
51
    if name != None and last[0] != name: return None # input is empty
52
    return last[1]
53

    
54
def merge_tagged(root):
55
    '''Merges siblings in root that are marked as mergeable.
56
    Used to recombine pieces of nodes that were split apart in the mappings.
57
    '''
58
    for name in set((c.tagName for c in xpath.get(root, '*[@merge=1]'))):
59
        xml_dom.merge_by_name(root, name)
60
    
61
    # Recurse
62
    for child in xml_dom.NodeElemIter(root): merge_tagged(child)
63

    
64
funcs = {}
65

    
66
##### Public functions
67

    
68
def is_func_name(name):
69
    return name.startswith('_') and name != '_' # '_' is default root node name
70

    
71
def is_func(node): return is_func_name(node.tagName)
72

    
73
def is_xml_func_name(name): return is_func_name(name) and name in funcs
74

    
75
def is_xml_func(node): return is_xml_func_name(node.tagName)
76

    
77
def simplify(node):
78
    '''Simplifies the XML functions in an XML tree.
79
    * Merges nodes tagged as mergable
80
    * Applies pass-through optimizations for XML functions
81
    '''
82
    for child in xml_dom.NodeElemIter(node): simplify(child)
83
    merge_tagged(node)
84
    
85
    func_name = node.tagName
86
    if not is_func_name(func_name): return # not a function
87
    
88
    params = list(xml_dom.NodeElemIter(node))
89
    
90
    # Pass-through optimizations
91
    if len(params) == 1: # single arg
92
        param = params[0]
93
        name = param.tagName
94
        value = param.firstChild
95
        
96
        is_agg_func = name.isdigit()
97
        is_if_no_cond = func_name = '_if' # no if condition means False
98
        if is_agg_func or (is_if_no_cond and name == 'else'):
99
            xml_dom.replace(node, value)
100
        elif is_if_no_cond and name == 'then': xml_dom.remove(node)
101

    
102
def process(node, on_error=exc.reraise, is_rel_func=None, db=None):
103
    '''Evaluates the XML functions in an XML tree.
104
    @param is_rel_func None|f(str) Tests if a name is a relational function.
105
        * If != None: Non-relational functions are removed, or relational
106
          functions are treated specially, depending on the db param (below).
107
    @param db
108
        * If None: Non-relational functions other than structural functions are
109
          replaced with their last parameter (usually the value), not evaluated.
110
          This is used in column-based mode to remove XML-only functions.
111
        * If != None: Relational functions are evaluated directly. This is used
112
          in row-based mode to combine relational and XML functions.
113
    '''
114
    has_rel_funcs = is_rel_func != None
115
    assert db == None or has_rel_funcs # rel_funcs required if db set
116
    
117
    for child in xml_dom.NodeElemIter(node):
118
        process(child, on_error, is_rel_func, db)
119
    merge_tagged(node)
120
    
121
    name = node.tagName
122
    if not is_func_name(name): return node # not any kind of function
123
    
124
    row_mode = has_rel_funcs and db != None
125
    column_mode = has_rel_funcs and db == None
126
    func = funcs.get(name, None)
127
    items = list(xml_dom.NodeTextEntryIter(node))
128
    
129
    # Parse function
130
    if len(items) == 1 and items[0][0].isdigit(): # has single numeric param
131
        # pass-through optimization for aggregating functions with one arg
132
        value = items[0][1] # pass through first arg
133
    elif row_mode and (is_rel_func(name) or func == None): # row-based mode
134
        try: value = sql_io.put(db, name, dict(items)) # evaluate using DB
135
        except sql.DoesNotExistException: return # preserve unknown funcs
136
            # possibly a built-in function of db_xml.put()
137
    elif column_mode or func == None:
138
        # local XML function can't be used or does not exist
139
        if column_mode and is_rel_func(name): return # preserve relational funcs
140
        # otherwise XML-only in column mode, or DB-only in XML output mode
141
        value = pop_value(items, None) # just replace with last param
142
    else: # local XML function
143
        try: value = func(items, node)
144
        except Exception, e: # also catch non-wrapped exceptions (XML func bugs)
145
            # Save in case another exception raised, overwriting sys.exc_info()
146
            exc.add_traceback(e)
147
            str_ = strings.ustr(node)
148
            exc.add_msg(e, 'function:\n'+str_)
149
            xml_dom.replace(node, xml_dom.mk_comment(node.ownerDocument,
150
                '\n'+term.emph_multiline(str_)))
151
                
152
            on_error(e)
153
            return # in case on_error() returns
154
    
155
    xml_dom.replace_with_text(node, value)
156

    
157
##### XML functions
158

    
159
# Function names must start with _ to avoid collisions with real tags
160
# Functions take arguments (items, node)
161

    
162
#### Transforming values
163

    
164
def repl(repls, value):
165
    '''Raises error if value not in map and no special '*' entry
166
    @param repls dict repl:with
167
        repl "*" means all other input values
168
        with "*" means keep input value the same
169
        with "" means ignore input value
170
    '''
171
    try: new_value = repls[value]
172
    except KeyError, e:
173
        # Save traceback right away in case another exception raised
174
        fe = FormatException(e)
175
        try: new_value = repls['*']
176
        except KeyError: raise fe
177
    if new_value == '*': new_value = value # '*' means keep input value the same
178
    return new_value
179

    
180
def _map(items, node):
181
    '''See repl()
182
    @param items
183
        <last_entry> Value
184
        <other_entries> name=value Mappings. Special values: See repl() repls.
185
    '''
186
    value = pop_value(items)
187
    if value == None: return None # input is empty
188
    return util.none_if(repl(dict(items), value), u'') # empty value means None
189
funcs['_map'] = _map
190

    
191
def _replace(items, node):
192
    items = conv_items(strings.ustr, items) # get *once* from iter, check types
193
    value = pop_value(items)
194
    if value == None: return None # input is empty
195
    try:
196
        for repl, with_ in items:
197
            if re.match(r'^\w+$', repl):
198
                repl = r'(?<![^\W_])'+repl+r'(?![^\W_])' # match whole word
199
            value = re.sub(repl, with_, value)
200
    except sre_constants.error, e: raise SyntaxError(e)
201
    return util.none_if(value.strip(), u'') # empty strings always mean None
202
funcs['_replace'] = _replace
203

    
204
#### Quantities
205

    
206
def _units(items, node):
207
    value = pop_value(items)
208
    if value == None: return None # input is empty
209
    
210
    quantity = units.str2quantity(value)
211
    try:
212
        for action, units_ in items:
213
            units_ = util.none_if(units_, u'')
214
            if action == 'default': units.set_default_units(quantity, units_)
215
            elif action == 'to':
216
                try: quantity = units.convert(quantity, units_)
217
                except ValueError, e: raise FormatException(e)
218
            else: raise SyntaxError(ValueError('Invalid action: '+action))
219
    except units.MissingUnitsException, e: raise FormatException(e)
220
    return units.quantity2str(quantity)
221
funcs['_units'] = _units
222

    
223
def parse_range(str_, range_sep='-'):
224
    default = (str_, None)
225
    start, sep, end = str_.partition(range_sep)
226
    if sep == '': return default # not a range
227
    if start == '' and range_sep == '-': return default # negative number
228
    return tuple(d.strip() for d in (start, end))
229

    
230
def _rangeStart(items, node):
231
    items = dict(conv_items(strings.ustr, items))
232
    try: value = items['value']
233
    except KeyError: return None # input is empty
234
    return parse_range(value)[0]
235
funcs['_rangeStart'] = _rangeStart
236

    
237
def _rangeEnd(items, node):
238
    items = dict(conv_items(strings.ustr, items))
239
    try: value = items['value']
240
    except KeyError: return None # input is empty
241
    return parse_range(value)[1]
242
funcs['_rangeEnd'] = _rangeEnd
243

    
244
def _range(items, node):
245
    items = dict(conv_items(float, items))
246
    from_ = items.get('from', None)
247
    to = items.get('to', None)
248
    if from_ == None or to == None: return None
249
    return str(to - from_)
250
funcs['_range'] = _range
251

    
252
def _avg(items, node):
253
    count = 0
254
    sum_ = 0.
255
    for name, value in conv_items(float, items):
256
        count += 1
257
        sum_ += value
258
    if count == 0: return None # input is empty
259
    else: return str(sum_/count)
260
funcs['_avg'] = _avg
261

    
262
class CvException(Exception):
263
    def __init__(self):
264
        Exception.__init__(self, 'CV (coefficient of variation) values are only'
265
            ' allowed for ratio scale data '
266
            '(see <http://en.wikipedia.org/wiki/Coefficient_of_variation>)')
267

    
268
def _noCV(items, node):
269
    items = list(conv_items(strings.ustr, items))
270
    try: name, value = items.pop() # last entry contains value
271
    except IndexError: return None # input is empty
272
    if re.match('^(?i)CV *\d+$', value): raise FormatException(CvException())
273
    return value
274
funcs['_noCV'] = _noCV
275

    
276
#### Names
277

    
278
_name_parts_slices_items = [
279
    ('first', slice(None, 1)),
280
    ('middle', slice(1, -1)),
281
    ('last', slice(-1, None)),
282
]
283
name_parts_slices = dict(_name_parts_slices_items)
284
name_parts = [name for name, slice_ in _name_parts_slices_items]
285

    
286
def _name(items, node):
287
    items = dict(list(conv_items(strings.ustr, items)))
288
    parts = []
289
    for part in name_parts:
290
        if part in items: parts.append(items[part])
291
    if not parts: return None # pass None values through; handle no name parts
292
    return ' '.join(parts)
293
funcs['_name'] = _name
294

    
295
#### Angles
296

    
297
def _compass(items, node):
298
    '''Converts a compass direction (N, NE, NNE, etc.) into a degree heading'''
299
    items = dict(conv_items(strings.ustr, items))
300
    try: value = items['value']
301
    except KeyError: return None # input is empty
302
    
303
    if not value.isupper(): return value # pass through other coordinate formats
304
    try: return util.cast(str, angles.compass2heading(value)) # ignore None
305
    except KeyError, e: raise FormatException(e)
306
funcs['_compass'] = _compass
(37-37/40)