Class attributeproxy

source code

object --+    
         |    
  property --+
             |
            attributeproxy

Expose an XML attribute of an Element subclass as Python instance attribute with support for an optional default value.

The .getAttribute() and .setAttribute() methods of the instance to which this is attached are used to retrieve and set the unicode attribute value, respectively.

When retrieving a value, the function given via the dec keyword argument will be used to convert the unicode into a native Python object (the default is to leave the unicode value as unicode). When setting a value, the function given via the enc keyword argument will be used to convert a native Python object to a unicode string.

When retrieving a value, if .getAttribute() raises KeyError then AttributeError is raised unless a default value is provided in which case it is returned instead.

If doc is provided it will be used as the documentation string, otherwise a default documentation string will be constructed identifying the attribute's name and explaining the default value if one is set.

NOTE: If an XML document is parsed and an element is encountered that does not have a value set for an attribute whose corresponding attributeproxy has a default value defined, then Python codes will be told the default value. Therefore, the default value given here must match what the XML DTD says the default value is for that attribute. Likewise, attributes for which the DTD does not define a default must not have a default defined here. These conditions must both be met to not create a discrepancy between the behaviour of Python codes relying on this I/O library and other interfaces to the same document.

Example:

>>> class Test(Element):
...     Scale = attributeproxy(u"Scale", enc = u"%.17g".__mod__, dec = float, default = 1.0, doc = "This is the scale (default = 1).")
...
>>> x = Test()
>>> # have not set value, default will be returned
>>> x.Scale
1.0
>>> x.Scale = 16
>>> x.Scale
16.0
>>> # default can be retrieved via the .default attribute of the
>>> # class attribute
>>> Test.Scale.default
1.0
>>> # default is read-only
>>> Test.Scale.default = 2.
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
AttributeError: can't set attribute
>>> # internally, value is stored as unicode (for XML)
>>> x.getAttribute("Scale")
u'16'
>>> # deleting an attribute restores the default value if defined
>>> del x.Scale
>>> x.Scale
1.0

property attribute