-
Notifications
You must be signed in to change notification settings - Fork 6
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
0 parents
commit b2e61d7
Showing
2 changed files
with
261 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,41 @@ | ||
===================== | ||
Generic API Doc Views | ||
===================== | ||
|
||
Get a browser started: | ||
|
||
>>> from zope.testbrowser.testing import Browser | ||
>>> browser = Browser() | ||
>>> browser.addHeader('Authorization', 'Basic mgr:mgrpw') | ||
|
||
|
||
Not Found View | ||
-------------- | ||
|
||
The `APIDOC` skin defines a custom not found view, since it fits the look and | ||
feel better and does not have all the O-wrap clutter: | ||
|
||
>>> browser.open('http://localhost/++apidoc++/non-existent/') | ||
Traceback (most recent call last): | ||
... | ||
HTTPError: HTTP Error 404: Not Found | ||
|
||
>>> from urllib2 import HTTPError | ||
>>> try: | ||
... browser.open('http://localhost/++apidoc++/non-existent/') | ||
... except HTTPError, error: | ||
... pass | ||
|
||
>>> print error.read() # XXX error here | ||
<... | ||
<h1 class="details-header"> | ||
Page Not Found | ||
</h1> | ||
<BLANKLINE> | ||
<p> | ||
While broken links occur occassionally, they are considered bugs. Please | ||
report any broken link to | ||
<a href="mailto:zope3-dev@zope.org">zope3-dev@zope.org</a>. | ||
</p> | ||
... | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,220 @@ | ||
======================== | ||
Object Introspector View | ||
======================== | ||
|
||
The "Introspector" view provides access to information about the current | ||
obejct, the context of the introspector view. When in `devmode`, the | ||
introspector is simply available as follows: | ||
|
||
>>> from zope.testbrowser.testing import Browser | ||
>>> browser = Browser() | ||
>>> browser.addHeader('Authorization', 'Basic mgr:mgrpw') | ||
>>> browser.handleErrors = False | ||
|
||
>>> browser.open('http://localhost/manage') | ||
>>> browser.getLink('Introspector').click() # XXX error here | ||
|
||
The page starts with telling you the class/type | ||
|
||
>>> browser.getLink('zope.app.folder.folder.Folder').url | ||
'http://localhost/++apidoc++/Code/zope/app/folder/folder/Folder/index.html' | ||
|
||
and the name of the object: | ||
|
||
>>> '<no name>' in browser.contents | ||
True | ||
|
||
Of course, the root folder does not have a name. As you can see the type links | ||
directly to the API documentation of the class. | ||
|
||
The next section lists all directly provided interfaces. The root folder | ||
directly provides the ``ISite`` and ``IRootFolder`` interface, so we should | ||
see those: | ||
|
||
>>> browser.getLink('zope.app.component.interfaces.ISite').url | ||
'.../++apidoc++/Interface/zope.app.component.interfaces.ISite/index.html' | ||
|
||
>>> browser.getLink('zope.app.folder.interfaces.IRootFolder').url | ||
'...apidoc++/Interface/zope.app.folder.interfaces.IRootFolder/index.html' | ||
|
||
The next two section, the implemented interfaces and the base classes, are not | ||
instance specific pieces of information, but they are still nice to see at | ||
this point. For example, a ``Folder`` instance provides the following | ||
interfaces: | ||
|
||
>>> browser.getLink('zope.app.folder.interfaces.IFolder').url | ||
'.../++apidoc++/Interface/zope.app.folder.interfaces.IFolder/index.html' | ||
|
||
>>> browser.getLink('persistent.interfaces.IPersistent').url | ||
'.../++apidoc++/Interface/persistent.interfaces.IPersistent/index.html' | ||
|
||
>>> browser.getLink('zope.app.component.interfaces.IPossibleSite').url | ||
'.../Interface/zope.app.component.interfaces.IPossibleSite/index.html' | ||
|
||
>>> browser.getLink('zope.app.container.interfaces.IContained').url | ||
'...doc++/Interface/zope.app.container.interfaces.IContained/index.html' | ||
|
||
The base classes of the ``Folder`` are as follows: | ||
|
||
>>> browser.getLink('persistent.Persistent').url | ||
'http://localhost/++apidoc++/Code/persistent/Persistent/index.html' | ||
|
||
>>> browser.getLink('zope.app.component.site.SiteManagerContainer').url | ||
'...apidoc++/Code/zope/app/component/site/SiteManagerContainer/index.html' | ||
|
||
>>> browser.getLink('zope.app.container.contained.Contained').url | ||
'.../++apidoc++/Code/zope/app/container/contained/Contained/index.html' | ||
|
||
Now that we described the component and class level of the object, the view | ||
dives into some details. First it lists the attributes/properties of the | ||
object, including the value of the attribute. This is information can be very | ||
useful when debugging an application. The only attribute of the folder is the | ||
data attribute: | ||
|
||
>>> print browser.contents | ||
<!DOCTYPE... | ||
... | ||
<h2>Attributes/Properties</h2> | ||
<div class="indent"> | ||
<ul class="attr-list"> | ||
<li> | ||
<b><code>data</code></b> | ||
... | ||
<br /> | ||
<i>Value:</i> | ||
<code><BTrees._OOBTree.OOBTree object at ...></code> | ||
<br /> | ||
<span class="small"> | ||
<i>Permissions:</i> | ||
n/a | ||
<span>(read)</span>, | ||
n/a | ||
<span>(write)</span> | ||
</span> | ||
</li> | ||
</ul> | ||
</div> | ||
... | ||
|
||
There are, however, several methods since the full mapping interface is | ||
implemented. Like for the class method documentation, the method's signature, | ||
doc string, permissions and the interface the method is declared in. Here an | ||
example: | ||
|
||
>>> print browser.contents | ||
<!DOCTYPE... | ||
... | ||
<h2>Methods</h2> | ||
<div class="indent"> | ||
<ul class="attr-list"> | ||
<li> | ||
<b><code>get(name, default=None)</code> | ||
</b><br> | ||
<div class="inline documentation"><p>Return ... </div> | ||
<span class="small"> | ||
<i>Interface:</i> | ||
<a href="...">zope.interface.common.mapping.IReadMapping</a><br /> | ||
</span> | ||
<span class="small"> | ||
<i>Permissions:</i> | ||
zope.View | ||
<span>(read)</span>, | ||
n/a | ||
<span>(write)</span> | ||
</span> | ||
</li> | ||
... | ||
</ul> | ||
</div> | ||
... | ||
|
||
Towards the bottom of the page, there are some optional sections. Some | ||
objects, for example our root folder, are inheritely mappings or | ||
sequences. Their data then is often hard to see in the attributes section, so | ||
they are provided in a aseparate section. To see anything useful, we have to | ||
add an object to the folder first: | ||
|
||
>>> import re | ||
>>> browser.getLink(re.compile('^File$')).click() | ||
>>> import cStringIO | ||
>>> browser.getControl('Data').value = cStringIO.StringIO('content') | ||
>>> browser.getControl(name='add_input_name').value = 'file.txt' | ||
>>> browser.getControl('Add').click() | ||
>>> browser.getLink('Introspector').click() | ||
|
||
Now the introspector will show the file and allow you to click on it: | ||
|
||
>>> print browser.contents | ||
<!DOCTYPE... | ||
... | ||
<h2>Mapping Items</h2> | ||
<div class="indent"> | ||
<ul class="attr-list"> | ||
<li> | ||
<b> | ||
<code>u'file.txt'</code> | ||
</b> | ||
<br /> | ||
<a href="++items++file.txt/@@introspector.html"> | ||
<code><zope.app.file.file.File object at ...></code> | ||
</a> | ||
(<span>type:</span> | ||
<a href="...zope/app/container/contained/ContainedProxy/index.html"> | ||
<code>ContainedProxy</code></a>) | ||
</li> | ||
</ul> | ||
</div> | ||
... | ||
|
||
The final section of the introspector displays the annotations that are | ||
declared for the object. The standard annotation that almost every object | ||
provides is the Dublin Core: | ||
|
||
>>> print browser.contents | ||
<!DOCTYPE... | ||
... | ||
<h2>Annotations</h2> | ||
<div class="indent"> | ||
<ul class="attr-list"> | ||
<li> | ||
<b> | ||
<code>'zope.app.dublincore.ZopeDublinCore'</code> | ||
</b> | ||
<br /> | ||
<a href="++annotations++zope.app.dublincore.ZopeDublinCore/@@int..."> | ||
<code><...annotatableadapter.ZDCAnnotationData ...></code> | ||
</a> | ||
(<span>type:</span> | ||
<a href="...lincore/annotatableadapter/ZDCAnnotationData/index.html"> | ||
<code>ZDCAnnotationData</code></a>) | ||
</li> | ||
... | ||
</ul> | ||
</div> | ||
... | ||
|
||
As you can see you can click on the annotation to discover it further: | ||
|
||
>>> browser.getLink('annotatableadapter.ZDCAnnotationData').click() | ||
>>> print browser.contents | ||
<!DOCTYPE... | ||
... | ||
<h2>Attributes/Properties</h2> | ||
<div class="indent"> | ||
<ul class="attr-list"> | ||
<li> | ||
<b><code>data</code></b> | ||
(<span>type:</span> | ||
<a href=".../++apidoc++/Code/__builtin__/dict/index.html"> | ||
<code>dict</code></a>) | ||
<br /> | ||
<i>Value:</i> | ||
<code>{u'Date.Modified': (u'...',), u'Creator': (u'zope.mgr',)}</code> | ||
<br /> | ||
</li> | ||
</ul> | ||
</div> | ||
... | ||
|
||
That's it! The introspector view has a lot more potential, but that's for | ||
someone else to do. |