81455 sbp #!/usr/bin/env python """ fieldtree.py - Field Tree Object Author: Sean B. Palmer, inamidst.com The FieldTree object is a kind of OrderedDict. The name Field refers to a label and value pair, usually called an item in Python. There are two main extra features that a FieldTree provides over an OrderedDict. The first is that when a field is set, it returns a Key object. This provides a kind of permanent link to the field. The second is that there are methods that allow for the access of any FieldTree objects nested inside a FieldTree. New FieldTree objects can be constructed without arguments: >>> person = FieldTree() You can add fields and keep the resulting keys: >>> a = person.add('gender', 'male') >>> b = person.add('name', 'John Smith') >>> c = person.add('website', 'example.com') Or you can add fields and discard the keys: >>> person['phone'] = '123-456-7890' >>> person['email'] = 'john@example.com' You can then access fields by key or by label: >>> person[b] 'John Smith' >>> person['website'] 'example.com' The useful thing about keys is that you can use them to access fields that you might then want to modify, and they'll be available after those modifications. So if we make a template from a FieldTree: >>> def format(person): ... args = person[b], person[a], person[c] ... return 'Name: %s, Sex: %s, Website: %s' % args This works in the expected way: >>> format(person) 'Name: John Smith, Sex: male, Website: example.com' But then even if you start adding and modifying values: >>> f = person.before(c, 'company', 'Acme Ltd.') >>> person.changelabel(a, 'sex') So that the data has a different label and a new order: >>> for field in person.fields(): ... print field ... ('sex', 'male') ('name', 'John Smith') ('company', 'Acme Ltd.') ('website', 'example.com') ('phone', '123-456-7890') ('email', 'john@example.com') The template still works! >>> format(person) 'Name: John Smith, Sex: male, Website: example.com' Now, let's say we want to use a FieldTree structure for the name so that we can store the forename and surname separately. We'll make this FieldTree by passing some field arguments: >>> name = FieldTree(('forename', 'John'), ('surname', 'Smith')) And then we can query the new object for its keys: >>> g = name.get_key('forename') >>> h = name.get_key('surname') We can then change the existing value of the 'name' label: >>> person['name'] = name And because this is a field tree, we can use the keys we got from the nested FieldTree to access its values from the parent tree: >>> person[g] 'John' >>> person['name'][h] 'Smith' But of course, we can't use labels to access nested values: >>> person['forename'] Traceback (most recent call last): ... KeyError: "no 'forename' label" Using labels in the regular way does work, though: >>> person['name']['forename'] 'John' Printing out all the fields iterates also over the nested fields, but it skips any FieldTree values themselves: >>> for field in person: ... print field ... ('sex', 'male') ('forename', 'John') ('surname', 'Smith') ('company', 'Acme Ltd.') ('website', 'example.com') ('phone', '123-456-7890') ('email', 'john@example.com') With FieldTree objects there is a general principle that you can use labels only on the current FieldTree object, but you can use keys in a nested way. So for example, you can check whether a FieldTree or any of its nested FieldTree objects contains a key: >>> a in person # gender/sex True >>> g in person # forename True But you can only check for labels in a non-nested way: >>> 'sex' in person True >>> 'name' in person True >>> 'forename' in person False You can iterate over all kinds of combinations of fields, labels, keys, and values using the iteration methods: >>> import itertools >>> def show(iter, num): ... return list(itertools.islice(iter, num)) To, for example, note that keys are a subclass of int: >>> show(person.keys(), 3) [Key(1), Key(2), Key(6)] And that labels (but not keys) referring to FieldTree object values are skipped, so that the following doesn't have 'name': >>> show(person.tree_labels(), 3) ['sex', 'forename', 'surname'] Another feature of FieldTree objects is that you can set values that don't have any labels. This means that you can only refer to this value using its key: >>> i = person.add('John Smith plays the trumpet') >>> person[i] 'John Smith plays the trumpet' >>> person.get_field(i) (Empty(), 'John Smith plays the trumpet') You can also delete values. You can't remove a whole field entirely, but delete replaces the current value with an Empty() object: >>> del person['phone'] >>> person['phone'] Empty() You can remove a field entirely, but it's not really recommended: >>> example = FieldTree(('a', 'b'), ('p', 'q')) >>> first = example.get_key('a') >>> example.remove(first) >>> len(example) 1 >>> example['a'] Traceback (most recent call last): ... KeyError: "no 'a' label" There are some other convenience functions for looking up various kinds of fields, keys, labels, and values: >>> person.get_field(g) ('forename', 'John') >>> person.get_label(g) 'forename' >>> person.get_value(g) 'John' """ import itertools class Key(int): __counter = itertools.count(1) def __repr__(self): return 'Key(%s)' % int(self) @staticmethod def next(): num = Key.__counter.next() return Key(num) class Empty(object): def __repr__(self): return 'Empty()' class FieldTree(object): def __init__(self, *args): self.__fields = {} # {key: (label, value)} self.__values = {} # {label: (key, value)} self.__order = [] # [keys] self.__trees = set() # [field-tree-values] for label, value in args: self[label] = value def __repr__(self): return 'FieldTree%s' % (tuple(self.fields()),) def __len__(self): return len(self.__order) def __contains__(self, obj): if isinstance(obj, Key): return self.has_tree_key(obj) else: return self.has_label(obj) def has_key(self, key): return self.__fields.has_key(key) def has_tree_key(self, key): for tree in [self] + list(self.__trees): if tree.has_key(key): return True return False def has_label(self, label): return self.__values.has_key(label) def __iter__(self): return self.tree_fields() def fields(self): for key in self.__order: yield self.__fields[key] def tree_fields(self): for key in self.__order: label, value = self.__fields[key] if isinstance(value, FieldTree): for field in value.tree_fields(): yield field else: yield label, value def keys(self): for key in self.__order: yield key def tree_keys(self): for key in self.__order: label, value = self.__fields[key] if isinstance(value, FieldTree): for vkey in value.tree_keys(): yield vkey else: yield key def labels(self): for label, value in self.fields(): yield label def tree_labels(self): for label, value in self.tree_fields(): yield label def values(self): for label, value in self.fields(): yield value def tree_values(self): for label, value in self.tree_fields(): yield value def __getitem__(self, item): return self.get_value(item) def get_field(self, key): "key -> field (deep)" assert isinstance(key, Key) if self.has_key(key): return self.__fields[key] for tree in self.__trees: try: return tree.get_field(key) except KeyError: continue raise KeyError("no %r key" % key) def get_key(self, label): "label -> key (shallow)" if self.has_label(label): return self.__values[label][0] else: raise KeyError("no %r label" % label) def get_label(self, key): "key -> label (deep)" return self.get_field(key)[0] def get_value(self, obj): "key -> value (deep) or label -> value (shallow)" if isinstance(obj, Key): return self.get_key_value(obj) else: return self.get_label_value(obj) def get_key_value(self, key): "key -> value (deep)" return self.get_field(key)[1] def get_label_value(self, label): "label -> value (shallow)" if self.has_label(label): return self.__values[label][1] else: raise KeyError("no %r label" % label) def __setitem__(self, obj, value): if not (obj in self): self.add(obj, value) else: self.changevalue(obj, value) def __arguments(self, args): if len(args) == 1: args = Empty(), args[0] elif len(args) != 2: raise ValueError("Expected one or two args") if any(isinstance(arg, Key) for arg in args): raise ValueError("FieldTrees can't contain Keys") return args def __set(self, args): label, value = self.__arguments(args) if self.has_label(label): key, oldvalue = self.__values[label] if isinstance(oldvalue, FieldTree): self.__trees.remove(oldvalue) else: key = Key.next() self.__fields[key] = (label, value) if not isinstance(label, Empty): self.__values[label] = (key, value) self.changed(key) return key def add(self, *args): key = self.__set(args) self.__order.append(key) return key def update(self, args): for label, value in args: self[label] = value def before(self, next, *args): if not self.has_key(next): raise KeyError("no %r key" % next) key = self.__set(args) index = self.__order.index(next) self.__order.insert(index, key) return key def __delitem__(self, obj): self.delete(obj) def delete(self, obj): self.changevalue(obj, Empty()) def remove(self, key): assert isinstance(key, Key) label, value = self.get_field(key) del self.__fields[key] del self.__values[label] self.__order.remove(key) if isinstance(value, FieldTree): self.__trees.remove(value) self.changed(key) def changelabel(self, key, label): if not self.has_key(key): raise KeyError("no %r key" % key) oldlabel, value = self.__fields[key] self.__fields[key] = (label, value) self.__values[label] = (key, value) self.changed(key) def changevalue(self, obj, value): if isinstance(obj, Key) and self.has_key(obj): key, (label, oldvalue) = obj, self.__fields[obj] elif self.has_label(obj): label, (key, oldvalue) = obj, self.__values[obj] else: raise KeyError("%r" % obj) self.__fields[key] = (label, value) self.__values[label] = (key, value) if isinstance(oldvalue, FieldTree): self.__trees.remove(oldvalue) if isinstance(value, FieldTree): self.__trees.add(value) self.changed(key) def changefield(self, key, label, value): self.changelabel(key, label) self.changevalue(key, value) self.changed(key) def changed(self, *keys): pass def test(): import doctest Documentation = type('Documentation', (object,), {'__doc__': __doc__}) doctest.run_docstring_examples(Documentation, globals(), verbose=True) def summary(): import sys, StringIO stdout = sys.stdout sys.stdout = StringIO.StringIO() test() buffer = sys.stdout sys.stdout = stdout buffer.seek(0) success, failure = 0, 0 for line in buffer: if line.startswith('ok'): success += 1 elif line.startswith('Fail'): failure += 1 print "%s/%s Tests Passed" % (success, success + failure) def main(): summary() if __name__ == '__main__': main() 3453291255 #swhack None TRUE