Module attrdef

source code

Attribute definitions for structures.

These are objects having at least the following attributes and methods:

• name -- will become the attribute name on the embedding class
• parseName -- the name of the XML/event element they can parse. This usually is identical to name, but may differ for compound attributes
• default -- may be Undefined, otherwise a valid value of the expected type
• description -- for user documentation
• typeDesc -- describing the content; this is usually a class attribute and intended for user documentation
• before -- the name of another attribute the attribute should precede in XML serializations. It is not an error to refer to an attribute that does not exist.
• feedObject(instance, ob) -> None -- adds ob to instance's attribute value. This will usually just result in setting the attribute; for compound attributes, this may instead append to a list, add to a set, etc.
• getCopy(instance, newParent, ctx) -> value -- returns the python value of the attribute in instance, copying mutable values (deeply) in the process.
• iterParentMethods() -> iter((name, value)) -- iterates over methods to be inserted into the parent class.
• makeUserDoc() -> returns some RST-valid string describing what the object is about.

They may have an attribute xmlName that allows parsing from xml elements named differently from the attribute. To keep things transparent, use this sparingly; the classic use case is with lists, where you can call an attribute options but have the XML element still be just "option".

AtomicAttributes, defined as those that are parsed from a unicode literal, add methods

• feed(ctx, instance, literal) -> None -- arranges for literal to be parsed and passed to feedObject. ctx is a parse context. The built-in method does not expect anything from this object, but structure has a default implementation containing an idmap and a propery registry.
• parse(self, value) -> anything -- returns a python value for the unicode literal value
• unparse(self, value) -> unicode -- returns a unicode object representing value and parseable by parse to that value.

This is not enough for complex attributes. More on those in the base.complexattrs module.

AttributeDefs *may* have a validate(instance) method. Structure instances will call them when they are done building. They should raise LiteralParseErrors if it turns out a value that looked right is not after all (in a way, they could catch validity rather than well-formedness violations, but I don't think this distinction is necessary here).

See structure on how to use all these.