22 from __future__
import absolute_import, division
24 from builtins
import object
30 """!A struct to which you can add any fields 32 Intended to be used for the return value from Task.run and other Task methods, 33 and useful for any method that returns multiple values. 35 The intent is to allow accessing returned items by name, instead of unpacking a tuple. 36 This makes the code much more robust and easier to read. It allows one to change what values are returned 37 without inducing mysterious failures: adding items is completely safe, and removing or renaming items 38 causes errors that are caught quickly and reported in a way that is easy to understand. 40 The primary reason for using Struct instead of dict is that the fields may be accessed as attributes, 41 e.g. aStruct.foo instead of aDict["foo"]. Admittedly this only saves a few characters, but it makes 42 the code significantly more readable. 44 Struct is preferred over named tuples, because named tuples can be used as ordinary tuples, thus losing 45 all the safety advantages of Struct. In addition, named tuples are clumsy to define and Structs 46 are much more mutable (e.g. one can trivially combine Structs and add additional fields). 50 """!Create a Struct with the specified field names and values 55 strVal = 'the value of the field named "strVal"', 60 @param[in] **keyArgs keyword arguments specifying name=value pairs 63 for name, val
in keyArgs.items():
66 def __safeAdd(self, name, val):
67 """!Add a field if it does not already exist and name does not start with __ (two underscores) 69 @param[in] name name of field to add 70 @param[in] val value of field to add 72 @throw RuntimeError if name already exists or starts with __ (two underscores) 74 if hasattr(self, name):
75 raise RuntimeError(
"Item %s already exists" % (name,))
76 if name.startswith(
"__"):
77 raise RuntimeError(
"Item name %r invalid; must not begin with __" % (name,))
78 setattr(self, name, val)
81 """!Return a dictionary of attribute name: value 83 @warning: the values are shallow copies. 88 """!Copy specified fields from another struct, provided they don't already exist 90 @param[in] struct struct from which to copy 91 @param[in] *nameList all remaining arguments are names of items to copy 93 For example: foo.copyItems(other, "itemName1", "itemName2") 94 copies other.itemName1 and other.itemName2 into self. 96 @throw RuntimeError if any item in nameList already exists in self 97 (but any items before the conflicting item in nameList will have been copied) 100 self.
__safeAdd(name, getattr(struct, name))
103 """!Return a one-level-deep copy (values are not copied) 108 return self.
__dict__ == other.__dict__
114 itemList = [
"%s=%r" % (name, val)
for name, val
in self.
getDict().items()]
115 return "%s(%s)" % (self.__class__.__name__,
"; ".join(itemList))
A struct to which you can add any fields.
def mergeItems(self, struct, nameList)
Copy specified fields from another struct, provided they don't already exist.
def __init__(self, keyArgs)
Create a Struct with the specified field names and values.
def copy(self)
Return a one-level-deep copy (values are not copied)
def getDict(self)
Return a dictionary of attribute name: value.
def __safeAdd(self, name, val)
Add a field if it does not already exist and name does not start with __ (two underscores) ...