2.2.2.1 API Conventions

There are four standard parameters that almost all attribute binding constructors accept. They always use the same parameter names, so you can supply them as keyword arguments.

attrName

The attrName parameter specifies the attribute name that the binding will have. As mentioned previously, this is only needed when the binding is being used in a class that doesn't support active descriptors. If you're using a class that inherits from binding.Component, you don't need to supply this parameter.

offerAs

The offerAs parameter is a sequence of configuration keys, such as interfaces or PropertyName objects. This is used for integration with the configuration system, so we'll explore it in more detail later on. For now, you can just ignore it.

doc

The doc parameter is an optional docstring which will be used for the attribute. This is useful for documenting your class so that tools like pydoc and the Python help function will display the docstring for the attribute as part of the class' documentation.

uponAssembly

uponAssembly is a flag that indicates whether the attribute should be computed when the object's uponAssembly method is called. We haven't covered ``assembly events" yet, so don't worry about this one for now.

adaptTo

adaptTo is an interface that the attribute's computed value should be adapted to, before it is cached or set. Since the adapt operation is done whenever the attribute is set, this effectively gives you built-in type checking and conversion for attributes.

suggestParent

suggestParent is a flag that indicates whether the referenced object should be informed that it is being attached to the referencing object, whenever the attribute is cached or set. This allows components to automatically discover their parent component and component name, if they do not already know their parent. By default, this flag is a true value, since most of the time you will want it to apply. However, if you know that the value of the attribute will never be a component, or that it will be a component that should not treat your object as its parent, you can set this flag to a false value.

noCache

noCache is a flag that indicates the attribute's computed value should not be cached. Note that this only stops the computed value from being stored: if you set the attribute, the value you set will be cached and reused until/unless the attribute is deleted. Set this flag to a true value if you do not want the computed value cached. (The default value is false.) (Note that if this flag is set, the suggestParent and adaptTo keywords will only affect setting the attribute, not computing it, since the value is not cached.)

permissionNeeded

permissionNeeded is either a peak.security.IAbstractPermission, or "None". This is a convenience feature for use with the peak.security package, so we won't deal further with it here.