Anonymous Inverses

Suppose we'd like to have a School kind, whose items have Person objects as "attendees". We could simply create a School class with an attendees attribute, and that would work fine... unless we needed a feature that only a bidirectional reference could provide, such as indexing. If we were the ones who created the Person class, we could perhaps edit it to add a school_attended attribute, but perhaps we don't control that code, or it would create a circular dependency between modules.

If we don't really care about having a school_attended attribute on the Person class, we can simply create an anonymous inverse attribute: a free-floating attribute that just defines what the inverse attribute "would have looked like" if it had existed on the original class.

To do this, we simply set the inverse of our attendees attribute to a new attribute descriptor of the desired cardinality (One or Sequence):

>>> class School(schema.Item):
...     attendees = schema.Sequence(Person, inverse=schema.One())

>>> joes_school = School(None, None, None, rv, "Hobart's", attendees=[Joe])

>>> list(joes_school.attendees)
[Joe Schmoe]

You must set the type of the main attribute (attendees in this case), so that the schema API will know what type the anonymous inverse attribute should be attached to (Person in this case). Both sides of the bidirectional reference can include a displayName, description, initialValue, or any of the other standard attribute descriptor arguments. (See the API Details section on Attribute Descriptors, below, for a complete list.)

You can't tell from the example above, but the inverse attribute actually gets attached to the Person kind, and the Joe item actually has an annotation attribute pointing to joes_school. You can get, set, or delete its value, as long as you know its automatically-generated attribute name:

>>> getattr(Joe, 'application.tests.School.attendees.inverse')
<School ... Hobart's>

And any modifications you make will of course propagate to the other side of the bidirectional reference:

>>> delattr(Joe, 'application.tests.School.attendees.inverse')

>>> list(joes_school.attendees)
[]

Notice that the generated name is a combination of:

1. the parcel name (from the module's __parcel__, if applicable)
2. the class name where the attribute was defined
3. the name of the attribute within the class
4. The word inverse

Note: we haven't talked about parcels yet, so for now you can assume that the first part is the module name where the class is found. (All the classes in this document are defined in the application.tests module for testing purposes.) The only time the first part will not be the module name, is if the module defines a __parcel__ setting in order to do Parcel Redirection (see below).)

Annotation Classes

Accessing "anonymous inverse" attributes can be inconvenient, and in any case they don't let you add anything but bidirectional references to an existing class. So, for more complex extensions, annotation classes are a better way to add attributes.

Annotations can be thought of as a kind of "data adapter" that allows you to extend existing objects with more information. They are different from subclassing, because an object can only be of one class at a time, but you may have as many different annotations for an object as you like. For example, you would not want to subclass Person to create a Teacher class, because a given person might also be an Employee, SoccerPlayer, or indeed also a Student at the same time! It is better to use annotations for such use cases, as they can be mixed and matched at will.

Another use of annotations is to better separate "concerns" or areas of functionality. For example, some Chandler objects define strictly "model" functionality in their base schema and methods, and then have one or more separate annotations that add UI data and methods. This avoids the need for different groups of developers to work on the same class at once, and it also means that it's always possible to create a different UI for the same basic object -- even if you're developing an entirely new UI from scratch that the original Chandler developers didn't envision. It also keeps the code simpler, makes each class individually more understandable, and prevents complicated circular dependencies (where module A depends on B, but B depends on A).

So, let's look at an example. Here, we'll define a Teacher annotation class that adds annotation attributes to the existing Person kind, to record who the teacher's supervisor is, and what certifications they have. We'll also create a linked TeachingCertificate class, so you can see how to create a bidirectional reference between an annotation and a new kind:

>>> class Teacher(schema.Annotation):
...     schema.kindInfo(annotates=Person)   # annotate the "Person" kind
...     certifications = schema.Sequence()
...     supervisor = schema.One(Person)

>>> class TeachingCertificate(schema.Item):
...     subject = schema.One(schema.Text)
...     certified_teachers = schema.Sequence(
...         Teacher, inverse=Teacher.certifications
...     )

Now let's create some instances. Annotation classes do not create persistent instances, however. Instead, their instances are just wrappers or adapters that give you access to the annotation attributes -- attributes that are actually stored in the wrapped item, just like an anonymous inverse. First, let's create a Teacher instance for Mary:

>>> ProfMary = Teacher(Mary)

The above expression can be read as "ProfMary is Mary playing the role of Teacher", or "ProfMary is Mary, viewed as a Teacher". The ProfMary object is not Mary herself; it's just her Teacher attributes. Let's give her a Phys. Ed. certificate:

>>> gym = TeachingCertificate("gym", rv, subject="Physical Education")
>>> ProfMary.certifications = [gym]

>>> list(ProfMary.certifications)
[<TeachingCertificate ... gym ...>]

So far, so good. The ProfMary object has a collection of certificates, and the certficate now knows Mary is certified:

>>> list(gym.certified_teachers)
[Mary Quite Contrary]

Notice that the certificate does not reference the ProfMary object; it refers directly to Mary herself. This is because the annotation attributes really belong to the Person class, and therefore to Mary herself. The Teacher object is just a way to conveniently access all -- and only -- the Teacher attributes of the object. You can think of it as being like an XML namespace or a filter that just gives you access to the teaching-related attributes of the person.

And, because annotation instances delegate all the attribute storage to the underlying, annotated item, you can create as many wrappers as you want for a given item and they will all share the same attribute values. In other words, no matter how many new Teacher(Mary) objects we create, they will all have the same certifications, because they really belong to Mary in the first place:

>>> list(Teacher(Mary).certifications)
[<TeachingCertificate ... gym ...>]

As with anonymous inverses, the attributes are actually "hidden" attributes added to the Person class, using an automatically-generated name. If you know the name, you can access the attributes directly, without using the annotation wrapper:

>>> list(getattr(Mary,'application.tests.Teacher.certifications'))
[<TeachingCertificate ... gym ...>]

But of course that's not very convenient. Sometimes, however, you may have code such as an attribute editor in the user interface that will need to know this full attribute name, because it will be dealing with the plain item and not an annotation wrapper. So, you should be aware that the attribute name is generated using the module name (or its __parcel__) plus the annotation class name and the attribute name within the annotation class. That way, if you need to get at it this way, you can.

As with anonymous inverses, setting or deleting the attribute on either the underlying item (full name) or the annotation wrapper (short name) has identical effects:

>>> setattr(Mary, 'application.tests.Teacher.supervisor', Joe)
>>> ProfMary.supervisor
Joe Schmoe

>>> del ProfMary.supervisor
>>> hasattr(Mary, 'application.tests.Teacher.supervisor')
False

Annotation wrappers do not have arbitrary attributes, however, only the ones that they were given in their schema:

>>> ProfMary.foo = "bar"
Traceback (most recent call last):
  ...
AttributeError: 'Teacher' object has no attribute 'foo'

or that were defined using __slots__ in the class definition:

>>> class Friend(schema.Annotation):
...     __slots__ = ["jabberConnection"]
...     schema.kindInfo(annotates=Person)
...     likes = schema.Sequence()
...     isLikedBy = schema.Sequence(inverse=likes)

>>> Friend(Mary).isLikedBy = [Joe]
>>> list(Friend(Joe).likes)
[Mary Quite Contrary]

The attributes defined using __slots__, however, are not persistent, and they will not be stored in the repository. Each annotation wrapper also has its own separate value for each attribute, no matter what item is wrapped. Thus, although each Friend(Mary) has the same isLikedBy (because it's actually stored by Mary), it has its own independent jabberConnection (because it's stored in a slot on the wrapper). This functionality is sometimes useful for annotations that have some runtime functionality that requires them to reference UI objects, connections to servers, or other non-persistent application objects:

>>> fMary = Friend(Mary)
>>> list(fMary.isLikedBy)
[Joe Schmoe]

>>> f2Mary = Friend(Mary)
>>> list(fMary.isLikedBy)
[Joe Schmoe]

>>> fMary.jabberConnection = "just pretending"
>>> f2Mary.jabberConnection = "another example"

>>> fMary.jabberConnection
'just pretending'

>>> f2Mary.jabberConnection
'another example'

Annotation class instances must wrap an instance of the type they were defined as annotating; thus you can't make a Teacher of anything but a Person (or subclass thereof):

>>> Teacher(gym)
Traceback (most recent call last):
  ...
TypeError: <class '...Teacher'> requires a <class '...Person'> instance

But you can wrap another annotation that wraps an item of the appropriate type, because all annotations of the passed-in item are stripped off first. Thus, we can easily convert a Friend to a Teacher or vice versa, since they are both Person annotations:

>>> Teacher(fMary)
Teacher(Mary Quite Contrary)

>>> Friend(ProfMary)
Friend(Mary Quite Contrary)

>>> Friend(Teacher(Friend(Friend(ProfMary))))
Friend(Mary Quite Contrary)

Finally, if you need to "un-annotate" an object to get at the persistent item it's wrapping, you can simply use its itsItem attribute:

>>> fMary.itsItem
Mary Quite Contrary

This is what the annotation classes themselves use, to remove an existing wrapper before creating a new one.

def installParcel(parcel, oldVersion=None):
    ...

Accessing Parcel Contents

Usually, your installParcel() code will need to refer to the contents of other parcels and modules. For example, when you create a menu item, you'll need to be able to refer to the menu it belongs in, and that menu item will be found in some other parcel. The schema.ns() API lets you conveniently access a parcel's items and the contents of its corresponding module through a single namespace.

You create this namespace by passing a module name and an item or repository view to schema.ns(). For example, if we want to access the application parcel and its corresponding Python module, we could do this:

>>> app_ns = schema.ns("application", rv)

The resulting object has attributes corresponding to the contents of the application module, e.g.:

>>> app_ns.schema
<module 'application.schema' ...>

It also has a parcel attribute, that refers to the actual schema.Parcel item in the repository, that holds all of the persistent schema for the associated module(s), along with any items created by the module's installParcel() function:

>>> app_ns.parcel
<Parcel (new): application ...>

So, if we create an item using the parcel as its parent, it will then be accessible by name from the namespace object:

>>> Person("Smitty", app_ns.parcel, fullname="I'm Smitty!")
I'm Smitty!

>>> app_ns.Smitty
I'm Smitty!

Note, however, that names defined in the module take precedence over names in the parcel, for purposes of retrieval. If you create a class named Person, and then also create an item whose name is Person, you will only see the Person class in the schema.ns() for your module, not the item. For example, if we add a Smitty variable to the application package, it will hide the Smitty item until we delete it again:

>>> import application
>>> application.Smitty = "Sorry, I'm not Smitty"

>>> app_ns.Smitty
"Sorry, I'm not Smitty"

If you need to access a "shadowed" item like this, you have to explicitly refer to the parcel item, and then use repository APIs to access the item directly:

>>> app_ns.parcel.getItemChild('Smitty')
I'm Smitty!

Or else remove the conflicting definition from the module:

>>> del application.Smitty
>>> app_ns.Smitty
I'm Smitty!

So, when you create items in your parcel, you should take care to give them names that don't conflict with class, variable, or function names in your module, or you will have to use more awkward ways of accessing them.

By the way, just a reminder... you can create a schema.ns() using any existing item, not just a repository view. Most often, you'll use the parcel argument passed in to your installParcel() function, but any persistent item will do. For example:

>>> tests_ns = schema.ns("application.tests", app_ns.parcel)

Installing or Updating Items

Your installParcel() function is responsible for creating or updating any persistent items you want in your parcel. Such items may include UI components such as menu items or detail views, tasks to be run at startup or periodically, preferences, collections, or any other persistent items.

Although the current version of Chandler doesn't support upgrading existing parcels without recreating the repository, future versions will. So, you should write your installParcel() with the assumption that future versions may call it to update an existing parcel.

This means you shouldn't just create items, without checking to see if they already exist, and possibly updating them instead. Since this would lead to quite a lot of repetitive code, the schema.Item class includes an update() classmethod that you can use to write simpler code. The update() method either updates an existing item or creates a new one, and in either case it returns the updated item. For example, here's an installParcel() function that creates or updates a Person item:

>>> def installParcel(parcel, old_version=None):
...     Person.update(parcel, "Carlos", fullname="Carlos Marron")

At the moment, there is no Carlos object in the application parcel:

>>> app_ns.Carlos
Traceback (most recent call last):
...
AttributeError: Carlos is not in <module...'application'...> or <Parcel...>

So, let's call installParcel() to create him:

>>> installParcel(app_ns.parcel)
>>> app_ns.Carlos
Carlos Marron

And we can call it again, since update() works on existing items:

>>> installParcel(app_ns.parcel)
>>> app_ns.Carlos
Carlos Marron

Now, let's change his name, and call installParcel() a third time:

>>> carlos = app_ns.Carlos
>>> carlos.fullname = "Charlie Brown"
>>> carlos.fullname
'Charlie Brown'

>>> installParcel(app_ns.parcel)
>>> carlos.fullname
'Carlos Marron'

As you can see, the update() call sets all the supplied attributes to the given values, so you can ensure that any items you update will have the values you set. Any attributes that the update() call does not set, however, will remain unchanged. For example:

>>> carlos.age = 27
>>> carlos.age
27

>>> installParcel(app_ns.parcel)
>>> carlos.age
27

In addition to updating attributes, the kind or class of the item are updated as well. For example:

>>> type(carlos)
<class '...Person'>

>>> class StrangePerson(Person):
...     """A silly example of changing an item's class/kind"""

>>> StrangePerson.update(app_ns.parcel, "Carlos")
Carlos Marron

>>> type(carlos)
<class '...StrangePerson'>

>>> installParcel(app_ns.parcel)
>>> type(carlos)
<class '...Person'>

Note that the update() method can't tell if you've renamed an object that should have the same name, or whether perhaps you've accidentally given two objects the same name, so you need to check these things yourself. If you need to delete old items or rename/relocate items in your installParcel() function, you should just use the normal repository APIs to do so. For example, if your parcel used to have a Carlos item that you now want to call Charlie, you should manually check for the item already existing, and then rename it by setting the itsName attribute.

Parcel Dependencies

A parcel "A" depends on another parcel "B" if any of the following are true:

• Any type defined in "A" has an attribute of a type found in "B"
• Any type defined in "A" is a subclass of a type found in "B"
• "A" defines an annotation class for an item class found in "B"
• An installParcel() function in "A" does any of the following:
  • Creates items of a type found in "B"
  • Calls schema.synchronize() with "B" as the target module (see Other APIs, below)
  • Uses schema.ns() to access the contents of the parcel corresponding to "B" (Note: "A" must actually refer to the parcel attribute of the ns instance, or to an item actually stored in the repository, or else a "B" parcel won't be created in the repository)
• "A" depends on some parcel "C", and "C" in turn depends on "B"

So, if you are creating a parcel "B", and there is some existing parcel "A" that will do one of the above things, you don't need to do anything special with your parcel layout. If you are creating a new parcel, however, that no other parcel depends on, you will need to either make it a top-level package on the parcel path, or you will need to modify an existing parcel to call schema.synchronize() so that your parcel will be loaded. Otherwise, there will be no way for Chandler to know it exists, so its code will never be run, and its items (if any) will never be created.

Note, by the way, that you should avoid circular dependencies between parcels, as these are likely to cause import difficulties, and are usually an indication that your design isn't as well-factored as it could be. For example, you are probably not taking full advantage of Anonymous Inverses and Annotation Classes, as these features make it much easier to avoid circular dependencies. (Because they allow you to define a class's core features in one parcel, and then add extended features in a separate parcel, so that the core class doesn't need to depend on everything that its extended features do.)

Abstract Item Classes

You can make an Item subclass abstract (non-instantiable) by setting __abstract__ = True in its class body:

>>> class Thing(schema.Item):
...     __abstract__ = True

>>> Thing()
Traceback (most recent call last):
  ...
TypeError: Thing is an abstract class; use a subclass instead

But subclasses of an abstract class are instantiable in the normal way:

>>> class Chair(Thing):
...     pass

>>> Chair('chair',rv)
<Chair ...>

This is useful when you want to define an abstract class that needs some methods to be defined or overridden in subclasses before it can be used.

Enumeration Classes

Sometimes, you have an attribute that you'd like to restrict to a set of fixed, pre-determined values. For example, suppose you want to be able to define attributes that contain a "feed type" value denoting one of the RSS/0.9, RSS/1.0, or ATOM feed formats. You can do this by creating an "enumeration" type, that can then be used as an attribute type. To do this, you subclass schema.Enumeration, and define a values attribute that contains a tuple of strings. Each string must be a valid Python identifier:

>>> class FeedFormat(schema.Enumeration):
...     """Format to be used for a feed"""
...     values = 'RSS_09', 'RSS_10', 'ATOM'

>>> class FeedGenerator(schema.Item):
...     format = schema.One(FeedFormat)
...     # other attributes would go here...

You can then set the defined attribute to any of the strings listed in the enumeration's values:

>>> fg = FeedGenerator('fg',rv, format = 'ATOM')
>>> fg.format
'ATOM'

But assigning an unlisted value will produce an error, if the repository view is using immediate error checking:

>>> fg.format = "fizzy_2"
Traceback (most recent call last):
  ...
ValueError: Assigning 'fizzy_2' to attribute 'format'...didn't match schema

Enumeration classes also can't be further subclassed:

>>> class ExtendedFormat(FeedFormat):
...     values = "ATOM_20", "FIZZY_19"
Traceback (most recent call last):
  ...
TypeError: Enumerations cannot subclass or be subclassed

And they can't include any attributes or methods besides values, which must be a tuple of strings:

>>> class BrokenEnum(schema.Enumeration):
...     values = "error"
Traceback (most recent call last):
  ...
TypeError: 'values' must be a tuple of 1 or more strings

>>> class BrokenEnum2(schema.Enumeration):
...     def foo(self): pass
Traceback (most recent call last):
  ...
TypeError: ("Only 'values' may be defined in an enumeration class", ...)

Struct Classes

Sometimes, it's useful to create "value" or "structure" types to use in a schema. For example, suppose that you need a "size" type with a width and a height. You can do this by subclassing schema.Struct and defining __slots__:

>>> class Size(schema.Struct):
...     __slots__ = 'width', 'height'

Struct instances are created using either positional arguments in the same order as the names in __slots__:

>>> my_size = Size(1,2)
>>> my_size
Size(1, 2)

>>> Size(4,5,6)
Traceback (most recent call last):
  ...
TypeError: ('Unexpected arguments', (6,))

or using keyword arguments with the same names as the slots:

>>> Size(height=1, width=2)
Size(2, 1)

And the instances have the attribute names as the defined slots:

>>> Size(1,2).width
1
>>> Size(1,2).height
2

Struct classes may include whatever methods you like, as well as having slots. You may not, however, create further subclasses of a given struct class:

>>> class BadExample(Size): pass
Traceback (most recent call last):
  ...
TypeError: Structs cannot subclass or be subclassed

NOTE: Structure instances are currently mutable; that is, you can change their attribute values. However, it is not recommended that you use this feature because it means there's a chance that changes won't be saved, unless you undertake to track the "dirty" state of the objects involved and use repository APIs to flag all items using the value as changed. It is therefore likely that a future version of the Schema API will make structure instances read-only once they are created. So, we recommend that you use code like this to change structure values:

someItem.window_size = Size(3,4)

Instead of code like this:

someItem.window_size.width = 3
someItem.window_size.height = 4

The first example will always cause the changes to be saved, but the second example requires additional steps (not shown) to ensure the changes to someItem are saved. In addition, if there was previously some code like this:

someItem.window_size = otherItem.window_size

Then changing the width and height of someItem.window_size would also affect the value of otherItem.window_size, and otherItem would therefore also need to be saved. This can create hard-to-find bugs, which is why the feature is deprecated.

Defining Clouds

Certain Chandler features such as item copying and sharing are controlled by schema information known as "clouds". A cloud is a named collection of endpoints, each of which sets an inclusion policy for an attribute. The inclusion policies indicate whether items referenced by that attribute should be included by value, by reference, or recursively by the item's clouds.

A complete discussion of clouds, inclusion policies, and how they are used is outside scope of this document, but we will explain here how to specify them. You should consult other Chandler documentation (such as for the sharing system) to determine what clouds your item classes should have and what policies you should use for individual attributes.

In fact, unless you were referred here by some other Chandler documentation, you should skip the remainder of this section. It will probably be quite confusing unless you already know why you would want to define a cloud or clouds for one of your item classes, and what effect the inclusion policies will have on the feature(s) you're trying to add support for.

To define clouds, just use the schema.addClouds() function in the body of your Item subclass. Each keyword argument names a cloud to be created, and its value must be a schema.Cloud() object:

>>> class ItemWithClouds(schema.Item):
...     foo = schema.One(schema.Text)
...     bar = schema.Sequence()
...     baz = schema.One(inverse=bar)
...     fiz = schema.Sequence(schema.Item)
...
...     schema.addClouds(
...         sharing = schema.Cloud(foo, "displayName"),
...         copying = schema.Cloud(byCloud = [fiz], byRef=[bar,baz]),
...     )

This then creates repository cloud items for the enclosing class:

>>> clouds = schema.itemFor(ItemWithClouds, rv).clouds
>>> list(clouds)
[<Cloud ... SharingCloud ...>, <Cloud ... CopyingCloud ...>]

schema.Cloud() objects specify the endpoints and inclusion policies for a cloud. The inclusion policies are given via keyword arguments (or the lack thereof), and attribute descriptors or attribute names are used to specify the endpoints themselves. For example, the sharing cloud defines two endpoints, for the foo and displayName attributes:

>>> sharing = clouds.getByAlias('sharing')
>>> list(sharing.endpoints)
[<Endpoint ... foo ...>, <Endpoint ... displayName ...>]

Because we simply listed these attributes without an explicit policy, the default byValue inclusion policy was applied:

>>> sharing.endpoints.getByAlias('foo').includePolicy
'byValue'

>>> sharing.endpoints.getByAlias('displayName').includePolicy
'byValue'

To specify any other inclusion policies, you must use keyword arguments naming the policy, and a list or tuple of attribute descriptors or attribute names. The copying cloud above created endpoints for the fiz, bar, and baz attributes, but with different policies:

>>> copying = clouds.getByAlias('copying')

>>> copying.endpoints.getByAlias('fiz').includePolicy
'byCloud'

>>> copying.endpoints.getByAlias('bar').includePolicy
'byRef'

>>> copying.endpoints.getByAlias('baz').includePolicy
'byRef'

Note that in most circumstances, you will want to specify endpoints using attribute descriptors directly, as we did in most of our example above. However, there are some times when it will be more useful or convenient to use an attribute name instead, as we did for the displayName attribute above. Also, there may be times when you need to specify an advanced endpoint option such as for the byMethod policy, which requires a method name to be specified in addition to the attribute name and policy. In cases like these, you may wish to directly create a schema.Endpoint object, for example:

>>> class CloudExample2(schema.Item):
...     bar = schema.Sequence()
...     baz = schema.One(inverse=bar)
...     schema.addClouds(
...         sharing = schema.Cloud(
...             byMethod = [
...                 schema.Endpoint(
...                     "bar", "bar", "byMethod", method="someMethod"
...                 )
...             ]
...         )
...     )

>>> sharing = schema.itemFor(CloudExample2, rv).clouds.getByAlias('sharing')

>>> sharing.endpoints.getByAlias('bar').includePolicy
'byMethod'

>>> sharing.endpoints.getByAlias('bar').method
'someMethod'

Note that you only need to use this if you need to specify a byMethod policy, a non-default cloudAlias for an endpoint, or a series of attributes instead of a single attribute.

A final note on defining clouds: the schema API implementation for Chandler 0.6 does not support defining clouds on annotation attributes, whether they are anonymous inverses or defined in an annotation class. This restriction may be lifted in 0.7 if needed.

Other Metadata

When a parcel is created, persistent items are created that correspond to each class, to store each class' schema. These items can have attributes of their own, such as displayName and description. Depending on whether the class is a schema.Item, schema.Struct, or schema.Enumeration, the attributes may be different, as the type of the persistent item will be different. For all classes, however, you can set attributes of the corresponding items by using the schema.kindInfo() function in the body of your item class:

>>> class CalendarItem(schema.Item):
...     """This is just a demo"""
...     schema.kindInfo(
...         displayName = "Calendar Item",
...     )

Once you've done this, the persistent item corresponding to your class in any given repository view, will have the attribute values you specify:

>>> schema.itemFor(CalendarItem, rv).displayName
'Calendar Item'

Note, however, that you can only specify names that correspond to valid attributes for whatever the corresponding item type is:

>>> class BadMetadata(schema.Item):
...     schema.kindInfo(madeUpName="xyz")
Traceback (most recent call last):
  ...
TypeError: 'madeUpName' is not an attribute of Kind

The only attribute used by all schema classes is displayName, which as we mentioned previously may be used by the Chandler UI in some places to show a name to the user. (You should therefore call the _() translation function on such strings before using them, although our examples in this document do not.) The schema.Annotation class also has an annotates attribute, as we saw in the section on Annotation Classes, above.

Whatever the attribute, however, you should note that their values are not inherited by subclasses:

>>> class CalendarItemSubclass(CalendarItem):
...     pass

>>> hasattr(schema.itemFor(CalendarItemSubclass, rv), 'displayName')
False

Also note that you can make multiple calls to kindInfo() in the same class:

>>> class MultipleMetadata(schema.Item):
...     schema.kindInfo(displayName="Foo")
...     schema.kindInfo(description="Bar")
>>> schema.itemFor(MultipleMetadata, rv).displayName
'Foo'
>>> schema.itemFor(MultipleMetadata, rv).description
'Bar'

as long as you don't change anything you set in a previous call:

>>> class ConflictingMetadata(schema.Item):
...     schema.kindInfo(displayName="Foo")
...     schema.kindInfo(displayName="Bar")
Traceback (most recent call last):
  ...
ValueError: 'displayName' defined multiple times for this class

And finally, note that calling kindInfo() is meaningless outside a class statement:

>>> schema.kindInfo(displayName="x")
Traceback (most recent call last):
  ...
SyntaxError: kindInfo() must be called in the body of a class statement