Introspector NG

Status

Author

Problem/Proposal

Early on in the development of Zope 3, we implemented an introspector view for any object that would tell us something about it. Unfortunately, the code was unmaintained and when apidoc came around it was totally useless. So currently it only shows the directly provided interfaces of the object and the class that forwards the user to apidoc.

This is a sad state, since the introspector has a lot of potential. I would like to reimplement it to fully use the apidoc API and still provide unique and valuable information about the object to the user.

Motivation/Goals

The SchoolTool? project recently hired me to develop some developer tools, including an improved introspector. So I started implementing the old functionality of the introspector (showing attributes and methods) using the apidoc API.

But then it hit me like a rock. What the introspector really wants to tell us about is the object itself, not its declaration. Basically it should describe the state (or data) of the object in the context of the declarations as completely as possible.

Thus, the goal of Inspector NG is to provide the developer with as much state information as possible.

Proposed Solution

The new introspector will provide a wide variety of information, utilizing the apidoc API as much as possible:

Name and Parent
Clearly the name of the object inside its containment should be shown. We asso want to provide a link back to the object's parent.

Note that the inspected object must have a location, otherwise there is no way to generate the links to other documentation sources. Of course, all objects in the ZODB have a location or can be located with a location proxy.
Contained/Contains
In this section we list the interfaces of the containers in which this object can reside. If the object is a container, we will also list the interfaces the container can contain.
Directly Implemented Interfaces
This is a nobrainer. Some objects have interfaces that are provided through them directly and not through a class. These interfaces should be separately be shown, since they often alter the behavior of an object in very distinct ways.
Attribute/Property Values
In apidoc's class view we show the default values for the attributes and properties. However, since we are dealing here with an instance, we can actually show the real values of the instance. Based on schema sna class information, We can also mark whether the current value is the default one or not.

Security Note: Of course, one should not be able to access all this data without the proper permissions, but remember that this is for the developer mode only and the benefit of inspecting the data quickly and freely is a huge benefit to the developer.
Sequence/Mapping Items
If the object is a sequence or a mapping, then the data is often not shown in the previous section. Here we should provide a detailed list of the items with links to their value's inspection screens for non-trivial values. Special namespaces will make this possible.
Annotations
A lot of additional data about an object is stored in its annotations. We cannot inspect all annotations, since they do not have to provide an enumeration API. However, the most important implementation IAttributeAnnotations provides the enumeration API and thus allows us to inspect the annotation items. Using again a special namespace, we can provide further introspection of the annotation values.

There is a lot of oppurtunity here to provide a whole lot of useful information. For example, with a couple of tricks, one could figure out which adapters are using a specific annotation.

Here is a screenshot of a partial SchoolTool? implementation:

Risks

I have already implemented this feature in SchoolTool? and it works great there. So we would only need to port the code.

Some people might have rightfully some security concerns, but please remember that this is for developer mode only and should never hit a production or even testing site.