Construct a data descriptor suitable for associating documentation with an attribute value. Attribute values are instance specific and are stored within the instance dictionary (so property values go away when the instance is garbage collected). Properties have a class-wide default
| 124 | return EnumType |
| 125 | |
| 126 | class Property(object): |
| 127 | """Construct a data descriptor suitable for associating |
| 128 | documentation with an attribute value. Attribute values are |
| 129 | instance specific and are stored within the instance dictionary |
| 130 | (so property values go away when the instance is garbage |
| 131 | collected). Properties have a class-wide default value used if |
| 132 | the property has not been specified on an instance. |
| 133 | |
| 134 | The class has the ability to indicate the access mode of the |
| 135 | resulting attribute. The possible access modes may be specified |
| 136 | using exactly one of the following enumeration values: |
| 137 | |
| 138 | Mode.READ_ONLY |
| 139 | ================== |
| 140 | The attribute may only be read. The instance property effectively |
| 141 | becomes a class constant (as the attribute may not be written). A |
| 142 | READ_ONLY attribute must have the default value specified when the |
| 143 | Property is constructed. |
| 144 | |
| 145 | Unlike an Enum class, the resulting Property is still accessable |
| 146 | through the declaring class (to provide access to the attribute |
| 147 | documentation). This has the side effect that the constant value |
| 148 | is only accessable through instances of the declaring class. |
| 149 | |
| 150 | Mode.READ_WRITE |
| 151 | =================== |
| 152 | The READ_WRITE mode is the default mode on Property instances and |
| 153 | is used to provide attributes with all the normal behaviors of |
| 154 | typical class attributes with supporting documentation and |
| 155 | optional default values. |
| 156 | |
| 157 | Mode.WRITE_ONCE |
| 158 | =================== |
| 159 | The WRITE_ONCE mode builds a data descriptor that allows every |
| 160 | instance of the declaring class to set the resulting attribute one |
| 161 | time. A default value may be specified that will be returned if |
| 162 | the attribute is accessed prior to the write; but the default does |
| 163 | not prevent the one-time write from occuring. |
| 164 | |
| 165 | Additionally you may supply a documentation string so your class |
| 166 | properties may expose usage information. |
| 167 | """ |
| 168 | |
| 169 | #### |
| 170 | # Special value used to mark an undefined default value. |
| 171 | #### |
| 172 | |
| 173 | __NONE = object() |
| 174 | |
| 175 | Mode = Enum('READ_ONLY', 'READ_WRITE', 'WRITE_ONCE') |
| 176 | |
| 177 | def __init__(self, name, default = __NONE, mode = Mode.READ_WRITE, doc = None): |
| 178 | """Construct a new Property data descriptor. |
| 179 | |
| 180 | \var{name} the name of the attribute being created. |
| 181 | \var{default} the (optional) default value to use when |
| 182 | retrieving the attribute if it hasn't already been set. |
| 183 | \var{mode} the mode of the constructed Property. |