gavo.base.attrdef module

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 property 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.

class gavo.base.attrdef.ActionAttribute(name, methodName, description='Undocumented', **kwargs)

Bases: UnicodeAttribute

An attribute definition for attributes triggering a method call on the parent instance.

They do create an attribute on parent which is None by default and the attribute value as a unicode string once the attribute was encountered. This could be used to handle multiple occurrences but is not in this basic definition.

feed(ctx, instance, value)

class gavo.base.attrdef.AtomicAttribute(name, default=None, description='Undocumented', copyable=False, aliases=None, callbacks=None, before=None)

Bases: AttributeDef

A base class for attributes than can be immediately parsed and unparsed from strings.

They need to provide a parse method taking a unicode object and returning a value of the proper type, and an unparse method taking a value of the proper type and returning a unicode string suitable for parse.

Note that you can, of course, assign to the attribute directly. If you assign crap, the unparse method is explicitly allowed to bomb in random ways; it just has to be guaranteed to work for values coming from parse (i.e.: user input is checked, programmatic input can blow up the thing; I consider this pythonesque :-).

feed(ctx, instance, value)

feedObject(instance, value)

getCopy(instance, newParent, ctx)

makeUserDoc()

parse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

unparse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

class gavo.base.attrdef.AttributeDef(name, default=None, description='Undocumented', copyable=False, aliases=None, callbacks=None, before=None)

Bases: object

is the base class for all attribute definitions.

See above.

The data attribute names have all an underscore added to avoid name clashes – structures should have about the same attributes and may want to have managed attributes called name or description.

When constructing AttributeDefs, you should only use keyword arguments, except for name (the first argument).

Note that an AttributeDef might be embedded by many instances. So, you must never store any instance data in an AttributeDef (unless it’s really a singleton, of course).

doCallbacks(instance, value)

should be called after feedObject has done its work.

feed(ctx, instance, value)

feedObject(instance, value)

getCopy(instance, newParent, ctx)

iterParentMethods()

returns an iterator over (name, method) pairs that should be inserted in the parent class.

makeUserDoc()

typeDesc_ = 'unspecified, invalid'

class gavo.base.attrdef.BooleanAttribute(name, default=None, description='Undocumented', copyable=False, aliases=None, callbacks=None, before=None)

Bases: AtomicAttribute

A boolean attribute.

Boolean literals are strings like True, false, on, Off, yes, No in some capitalization.

parse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

typeDesc_ = 'boolean'

unparse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

class gavo.base.attrdef.Computed

Bases: object

A sentinel class for computed (property) defaults.

Use this to construct AttributeDefs with defaults that are properties to inhibit assigning to them. This should only be required in calls of the superclass’s init.

class gavo.base.attrdef.EnumeratedUnicodeAttribute(name, default, validValues, **kwargs)

Bases: UnicodeAttribute

An attribute definition for an item that can only take on one of a finite set of values.

parse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

property typeDesc_

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

class gavo.base.attrdef.FloatAttribute(name, default=None, description='Undocumented', copyable=False, aliases=None, callbacks=None, before=None)

Bases: AtomicAttribute

An attribute definition for floating point attributes.

parse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

typeDesc_ = 'float'

unparse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

class gavo.base.attrdef.FunctionRelativePathAttribute(name, baseFunction, default=None, description='Undocumented', **kwargs)

Bases: UnicodeAttribute

A (utf-8 encoded) path relative to the result of some function at runtime.

This is used to make things relative to config items.

iterParentMethods()

returns an iterator over (name, method) pairs that should be inserted in the parent class.

parse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

unparse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

class gavo.base.attrdef.IdMapAttribute(name, default=None, description='Undocumented', copyable=False, aliases=None, callbacks=None, before=None)

Bases: AtomicAttribute

An attribute allowing a quick specification of identifiers to identifiers.

The literal format is <id>:<id>{,<id>:<id>},? with ignored whitespace.

parse(val)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

typeDesc_ = 'Comma-separated list of <identifier>:<identifier> pairs'

unparse(val)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

class gavo.base.attrdef.IntAttribute(name, default=None, description='Undocumented', copyable=False, aliases=None, callbacks=None, before=None)

Bases: AtomicAttribute

An attribute definition for integer attributes.

parse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

typeDesc_ = 'integer'

unparse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

exception gavo.base.attrdef.LiteralParseError(attName: str, literal: str, pos: Optional[ParsePosition] = None, hint: Optional[str] = None)

Bases: StructureError

is raised if an attribute literal is somehow bad.

LiteralParseErrors are constructed with the name of the attribute that was being parsed, the offending literal, and optionally a parse position and a hint.

class gavo.base.attrdef.NWUnicodeAttribute(name, **kwargs)

Bases: UnicodeAttribute

A UnicodeAttribute that has its whitespace normalized.

Normalization consists of stripping whitespace at the ends and replacing any runs or internal whitespace by a single blank. The whitespace will not be added back on unparsing.

parse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

typeDesc_ = 'whitespace normalized unicode string'

class gavo.base.attrdef.NotGiven

Bases: object

A sentinel class for defaultless values that can remain undefined.

class gavo.base.attrdef.RawAttribute(name, default=None, description='Undocumented', copyable=False, aliases=None, callbacks=None, before=None)

Bases: AtomicAttribute

An attribute definition that does no parsing at all.

This is only useful in “internal” structures that never get serialized or deserialized.

parse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

unparse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

class gavo.base.attrdef.StringListAttribute(name, **kwargs)

Bases: UnicodeAttribute

An attribute containing a list of comma separated strings.

The value is a list. This is similar to a complexattrs.ListOfAtoms with UnicodeAttribute items, except the literal is easier to write but more limited. Use this for the user’s convenience.

property default_

parse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

realDefault = []

typeDesc_ = 'Comma-separated list of strings'

unparse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

class gavo.base.attrdef.StringSetAttribute(name, **kwargs)

Bases: StringListAttribute

A StringListAttribute, except the result is a set.

property default_

parse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

realDefault = {}

class gavo.base.attrdef.Undefined

Bases: object

a sentinel for all kinds of undefined values.

Do not instantiate.

>>> Undefined()
Traceback (most recent call last):
TypeError: Undefined cannot be instantiated.
>>> bool(Undefined)
False
>>> repr(Undefined)
'<Undefined>'
>>> str(Undefined)
Traceback (most recent call last):
gavo.utils.excs.StructureError: Undefined cannot be stringified.

class gavo.base.attrdef.UnicodeAttribute(name, **kwargs)

Bases: AtomicAttribute

An attribute definition for an item containing a string.

This will decode bytes passed in assuming they’re utf-8 and fail if they’re not. Unparsing will not bring them back to bytes.

In addition to AtomicAttribute’s keywords, you can use strip (default false) to have leading and trailing whitespace be removed on parse. (Unparsing will not add it back).

You can also add expand (default False) to have UnicodeAttribute try and expand RD macros on the instance passed in. This of course only works if the attribute lives on a class that is a MacroPackage.

feed(ctx, instance, value)

parse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.

typeDesc_ = 'unicode string'

unparse(value)

returns a typed python value for the string representation value.

value can be expected to be a unicode string.