LSSTApplications  10.0-2-g4f67435,11.0.rc2+1,11.0.rc2+12,11.0.rc2+3,11.0.rc2+4,11.0.rc2+5,11.0.rc2+6,11.0.rc2+7,11.0.rc2+8
LSSTDataManagementBasePackage
struct.py
Go to the documentation of this file.
1 from __future__ import absolute_import, division
2 #
3 # LSST Data Management System
4 # Copyright 2008, 2009, 2010, 2011 LSST Corporation.
5 #
6 # This product includes software developed by the
7 # LSST Project (http://www.lsst.org/).
8 #
9 # This program is free software: you can redistribute it and/or modify
10 # it under the terms of the GNU General Public License as published by
11 # the Free Software Foundation, either version 3 of the License, or
12 # (at your option) any later version.
13 #
14 # This program is distributed in the hope that it will be useful,
15 # but WITHOUT ANY WARRANTY; without even the implied warranty of
16 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 # GNU General Public License for more details.
18 #
19 # You should have received a copy of the LSST License Statement and
20 # the GNU General Public License along with this program. If not,
21 # see <http://www.lsstcorp.org/LegalNotices/>.
22 #
23 __all__ = ["Struct"]
24 
25 class Struct(object):
26  """!A struct to which you can add any fields
27 
28  Intended to be used for the return value from Task.run and other Task methods,
29  and useful for any method that returns multiple values.
30 
31  The intent is to allow accessing returned items by name, instead of unpacking a tuple.
32  This makes the code much more robust and easier to read. It allows one to change what values are returned
33  without inducing mysterious failures: adding items is completely safe, and removing or renaming items
34  causes errors that are caught quickly and reported in a way that is easy to understand.
35 
36  The primary reason for using Struct instead of dict is that the fields may be accessed as attributes,
37  e.g. aStruct.foo instead of aDict["foo"]. Admittedly this only saves a few characters, but it makes
38  the code significantly more readable.
39 
40  Struct is preferred over named tuples, because named tuples can be used as ordinary tuples, thus losing
41  all the safety advantages of Struct. In addition, named tuples are clumsy to define and Structs
42  are much more mutable (e.g. one can trivially combine Structs and add additional fields).
43  """
44  def __init__(self, **keyArgs):
45  """!Create a Struct with the specified field names and values
46 
47  For example:
48  @code
49  myStruct = Struct(
50  strVal = 'the value of the field named "strVal"',
51  intVal = 35,
52  )
53  @endcode
54 
55  @param[in] **keyArgs keyword arguments specifying name=value pairs
56  """
57  object.__init__(self)
58  for name, val in keyArgs.iteritems():
59  self.__safeAdd(name, val)
60 
61  def __safeAdd(self, name, val):
62  """!Add a field if it does not already exist and name does not start with __ (two underscores)
63 
64  @param[in] name name of field to add
65  @param[in] val value of field to add
66 
67  @throw RuntimeError if name already exists or starts with __ (two underscores)
68  """
69  if hasattr(self, name):
70  raise RuntimeError("Item %s already exists" % (name,))
71  if name.startswith("__"):
72  raise RuntimeError("Item name %r invalid; must not begin with __" % (name,))
73  setattr(self, name, val)
74 
75  def getDict(self):
76  """!Return a dictionary of attribute name: value
77 
78  @warning: the values are shallow copies.
79  """
80  return self.__dict__.copy()
81 
82  def mergeItems(self, struct, *nameList):
83  """!Copy specified fields from another struct, provided they don't already exist
84 
85  @param[in] struct struct from which to copy
86  @param[in] *nameList all remaining arguments are names of items to copy
87 
88  For example: foo.copyItems(other, "itemName1", "itemName2")
89  copies other.itemName1 and other.itemName2 into self.
90 
91  @throw RuntimeError if any item in nameList already exists in self
92  (but any items before the conflicting item in nameList will have been copied)
93  """
94  for name in nameList:
95  self.__safeAdd(name, getattr(struct, name))
96 
97  def copy(self):
98  """!Return a one-level-deep copy (values are not copied)
99  """
100  return Struct(**self.getDict())
101 
102  def __eq__(self, other):
103  return self.__dict__ == other.__dict__
104 
105  def __len__(self):
106  return len(self.__dict__)
107 
108  def __repr__(self):
109  itemList = ["%s=%r" % (name, val) for name, val in self.getDict().iteritems()]
110  return "%s(%s)" % (self.__class__.__name__, "; ".join(itemList))
def __init__
Create a Struct with the specified field names and values.
Definition: struct.py:44
def copy
Return a one-level-deep copy (values are not copied)
Definition: struct.py:97
A struct to which you can add any fields.
Definition: struct.py:25
def __safeAdd
Add a field if it does not already exist and name does not start with __ (two underscores) ...
Definition: struct.py:61
def getDict
Return a dictionary of attribute name: value.
Definition: struct.py:75
def mergeItems
Copy specified fields from another struct, provided they don&#39;t already exist.
Definition: struct.py:82