API Reference

APIDoc

Zope 3 API Documentation

class zope.app.apidoc.apidoc.APIDocumentation(parent, name)

Bases: zope.app.apidoc.utilities.ReadContainerBase

The collection of all API documentation.

This documentation is implemented using a simply IReadContainer. The items of the container are all registered utilities for IDocumentationModule.

get(key, default=None)

Look up an IDocumentationModule utility with the given name.

If found, a copy of the utility with this object as its parent, created by withParentAndName(), will be returned.

items()

Return a sorted list of (name, utility) pairs for all registered IDocumentationModule objects.

Each utility returned will be a child of this object created with withParentAndName().

class zope.app.apidoc.apidoc.apidocNamespace(ob, request=None)

Bases: object

Used to traverse to an API Documentation.

Instantiating this object with a request will apply the zope.app.apidoc.browser.skin.APIDOC skin automatically.

zope.app.apidoc.apidoc.handleNamespace(ob, name)

Used to traverse to an API Documentation.

Class Registry

Class Registry

class zope.app.apidoc.classregistry.ClassRegistry

Bases: dict

A simple registry for classes.

getClassesThatImplement(iface)

Return all class items that implement iface.

Methods returns a sorted list of 2-tuples of the form (path, class).

getSubclassesOf(klass)

Return all class items that are proper subclasses of klass.

Methods returns a sorted list of 2-tuples of the form (path, class).

zope.app.apidoc.classregistry.classRegistry = {}

The global class registry object. Cleaned up in tests by zope.testing.cleanup.

zope.app.apidoc.classregistry.safe_import(path, default=None)

Import a given path as efficiently as possible and without failure.

Component

Component Inspection Utilities

zope.app.apidoc.component.getRequiredAdapters(iface, withViews=False)

Get global adapter registrations where the specified interface is required.

zope.app.apidoc.component.getProvidedAdapters(iface, withViews=False)

Get global adapter registrations where this interface is provided.

zope.app.apidoc.component.filterAdapterRegistrations(regs, iface, level=1)

Return only those registrations that match the specifed level

zope.app.apidoc.component.getClasses(iface)

Get the classes that implement this interface.

zope.app.apidoc.component.getFactories(iface)

Return the global factory registrations, who will return objects providing this interface.

zope.app.apidoc.component.getUtilities(iface)

Return all global utility registrations that provide the interface.

zope.app.apidoc.component.getRealFactory(factory)

Get the real factory.

Sometimes the original factory is masked by functions. If the function keeps track of the original factory, use it.

zope.app.apidoc.component.getParserInfoInfoDictionary(info)

Return a PT-friendly info dictionary for a parser info object.

zope.app.apidoc.component.getInterfaceInfoDictionary(iface)

Return a PT-friendly info dictionary for an interface.

zope.app.apidoc.component.getTypeInfoDictionary(type)

Return a PT-friendly info dictionary for a type.

zope.app.apidoc.component.getSpecificationInfoDictionary(spec)

Return an info dictionary for one specification.

zope.app.apidoc.component.getAdapterInfoDictionary(reg)

Return a PT-friendly info dictionary for an adapter registration.

zope.app.apidoc.component.getFactoryInfoDictionary(reg)

Return a PT-friendly info dictionary for a factory.

zope.app.apidoc.component.getUtilityInfoDictionary(reg)

Return a PT-friendly info dictionary for a factory.

Stubs for when documentation is disabled.

class zope.app.apidoc.disabled.APIDocStub

Bases: object

A stub to use as display context when APIDoc is disabled.

class zope.app.apidoc.disabled.apidocNamespace(ob, request=None)

Bases: object

Used to traverse to an API Documentation when it is disabled.

Interface

Interface Inspection Utilities

zope.app.apidoc.interface.getElements(iface, type=<InterfaceClass zope.interface.interfaces.IElement>)

Return a dictionary containing the elements in an interface.

The type specifies whether we are looking for attributes or methods.

zope.app.apidoc.interface.getFieldsInOrder(iface, _itemkey=<function <lambda>>)

Return a list of (name, field) tuples in native interface order.

zope.app.apidoc.interface.getAttributes(iface)

Returns a list of attributes specified in the interface.

zope.app.apidoc.interface.getMethods(iface)

Returns a list of methods specified in the interface.

zope.app.apidoc.interface.getFields(iface)

Returns a list of fields specified in the interface.

zope.app.apidoc.interface.getInterfaceTypes(iface)

Return a list of interface types that are specified for this interface.

Note that you should only expect one type at a time.

zope.app.apidoc.interface.getFieldInterface(field)

Return the interface representing the field.

zope.app.apidoc.interface.getAttributeInfoDictionary(attr, format=None)

Return a page-template-friendly information dictionary.

zope.app.apidoc.interface.getMethodInfoDictionary(method, format=None)

Return a page-template-friendly information dictionary.

zope.app.apidoc.interface.getFieldInfoDictionary(field, format=None)

Return a page-template-friendly information dictionary.

Interfaces

Generic API Documentation Interfaces

interface zope.app.apidoc.interfaces.IDocumentationModule

Extends: zope.location.interfaces.ILocation

Zope 3 API Documentation Module

A documentation module contains the documentation for one specific aspect of the framework, such as ZCML directives or interfaces.

The interface is used to register module as utilities.

title

Title

The title of the documentation module.

description

Module Description

This text describes the functionality of the module.

withParentAndName(parent, name)

Return a new object that is a copy of this object, but being located at the given parent and name.

Presentation

Views/Presentation Utilities

zope.app.apidoc.presentation.getViewFactoryData(factory)

Squeeze some useful information out of the view factory

zope.app.apidoc.presentation.getPresentationType(iface)

Get the presentation type from a layer interface.

zope.app.apidoc.presentation.getViews(iface, type=<InterfaceClass zope.publisher.interfaces.IRequest>)

Get all view registrations for a particular interface.

zope.app.apidoc.presentation.filterViewRegistrations(regs, iface, level=1)

Return only those registrations that match the specifed level

zope.app.apidoc.presentation.getViewInfoDictionary(reg)

Build up an information dictionary for a view registration.

Static

Retrieve Static APIDOC

zope.app.apidoc.static.cleanURL(url)

Clean a URL from parameters.

zope.app.apidoc.static.completeURL(url)

Add file to URL, if not provided.

class zope.app.apidoc.static.Link(url, rootURL, referenceURL='None')

Bases: object

A link in the page.

isLocalURL()

Determine whether the passed in URL is local and accessible.

class zope.app.apidoc.static.StaticAPIDocGenerator(options)

Bases: object

Static API doc Maker

retrieve()

Start the retrieval of the apidoc.

processLink(link)

Process a link.

Utilities

Utilties to make the life of Documentation Modules easier.

zope.app.apidoc.utilities.relativizePath(path)

Convert the path to a relative form.

zope.app.apidoc.utilities.truncateSysPath(path)

Remove the system path prefix from the path.

class zope.app.apidoc.utilities.ReadContainerBase

Bases: object

Base for zope.container.interfaces.IReadContainer objects.

class zope.app.apidoc.utilities.DocumentationModuleBase

Bases: zope.app.apidoc.utilities.ReadContainerBase

Support for implementing a documentation module.

withParentAndName(parent, name)

Subclasses need to override this if they are stateful.

zope.app.apidoc.utilities.getPythonPath(obj)

Return the path of the object in standard Python notation.

This method should try very hard to return a string, even if it is not a valid Python path.

zope.app.apidoc.utilities.isReferencable(path)

Return whether the Python path is referencable.

zope.app.apidoc.utilities.getPermissionIds(name, checker=<object object>, klass=<object object>)

Get the permissions of an attribute.

zope.app.apidoc.utilities.getFunctionSignature(func, ignore_self=False)

Return the signature of a function or method.

zope.app.apidoc.utilities.getPublicAttributes(obj)

Return a list of public attribute names.

zope.app.apidoc.utilities.getInterfaceForAttribute(name, interfaces=<object object>, klass=<object object>, asPath=True)

Determine the interface in which an attribute is defined.

zope.app.apidoc.utilities.columnize(entries, columns=3)

Place a list of entries into columns.

zope.app.apidoc.utilities.getDocFormat(module)

Convert a module’s __docformat__ specification to a renderer source id

zope.app.apidoc.utilities.dedentString(text)

Dedent the docstring, so that docutils can correctly render it.

Browser

Main API Documentation View

class zope.app.apidoc.browser.apidoc.APIDocumentationView

Bases: object

View for the API Documentation

getModuleList()

Get a list of all available documentation modules.

API Documentation macros

class zope.app.apidoc.browser.macros.APIDocumentationMacros(context, request)

Bases: zope.app.basicskin.standardmacros.StandardMacros

Page Template METAL macros for API Documentation

macro_pages = ('menu_macros', 'details_macros', 'static_menu_macros')

Macro pages

API Doc Preference Views

class zope.app.apidoc.browser.preference.APIDocPreferencesTree(context, request)

Bases: zope.app.tree.browser.cookie.CookieTreeView

Preferences Tree using the stateful cookie tree.

APIdoc skin.

interface zope.app.apidoc.browser.skin.apidoc

Extends: zope.publisher.interfaces.browser.IBrowserRequest

The apidoc layer.

interface zope.app.apidoc.browser.skin.APIDOC

Extends: zope.app.apidoc.browser.skin.apidoc, zope.publisher.interfaces.browser.IDefaultBrowserLayer

The APIDOC skin.

Common Utilities for Browser View

Book

Help books.

interface zope.app.apidoc.bookmodule.book.IBookModule

Extends: zope.app.apidoc.interfaces.IDocumentationModule

Interface API Documentation Module

This is a marker interface, so that we can write adapters for objects implementing this interface.

class zope.app.apidoc.bookmodule.book.BookModule(title, path)

Bases: zope.app.onlinehelp.onlinehelp.OnlineHelp

Represent a book compiled from various README.rst|txt and other *.rst|txt documentation files.

title = u'Book'

Title.

description = u"\n This is a developer's book compiled from all existing documentation\n files. It is not meant to be a complete or cohesive work, but each chapter\n in itself is a little story. Think about it like a collection of fairy\n tales.\n "

Description.

Configuration

Meta-Configuration Handlers for “apidoc:bookchapter” directive.

zope.app.apidoc.bookmodule.metaconfigure.bookchapter(_context, id, title, doc_path='/home/docs/checkouts/readthedocs.org/user_builds/zopeappapidoc/envs/issue10/lib/python2.7/site-packages/zope.app.apidoc-4.0.1.dev0-py2.7.egg/zope/app/apidoc/bookmodule/empty.txt', parent='', resources=None)

Register a book chapter

Schema for the apidoc:bookchapter directive

interface zope.app.apidoc.bookmodule.metadirectives.IBookChapterDirective

Register a new Book Chapter

id

Topic Id

Id of the chapter as it will appear in the URL.

title

Title

Provides a title for the chapter.

doc_path

Path to File

Path to the file that contains the chapter content.

parent

Parent Chapter

Id of the parent chapter.

resources

A list of resources.

A list of resources which shall be user for the chapter. The resources must be located in the same directory as the chapter.

Browser

Browser Views for Book

class zope.app.apidoc.bookmodule.browser.Menu

Bases: object

Menu View Helper Class

>>> class Chapter(object):
...     title = 'Read Me'
...     path = 'README.txt'
...
...     def getTopicPath(self):
...         return self.path[:-4]

>>> class Node(object):
...     def __init__(self, context):
...         self.context = context

>>> menu = Menu()

>>> chapter = Chapter()
>>> node = Node(chapter)
>>> menu.getMenuTitle(node)
'Read Me'

>>> menu.getMenuLink(node)
'README/show.html'
>>> chapter.path = EMPTYPATH
>>> menu.getMenuLink(node)

getMenuTitle(node)

Return the title of the node that is displayed in the menu.

getMenuLink(node)

Return the HTML link of the node that is displayed in the menu.

Code

Code Documentation Module

This module is able to take a dotted name of any class and display documentation for it.

class zope.app.apidoc.codemodule.codemodule.CodeModule

Bases: zope.app.apidoc.codemodule.module.Module

Represent the code browser documentation root

Initialize object.

title = u'Code Browser'

The title.

description = u'\n This module allows you to get an overview of the modules and classes\n defined in the Zope 3 framework and its supporting packages. There are\n two methods to navigate through the modules to find the classes you are\n interested in.\n\n The first method is to type in some part of the Python path of the class\n and the module will look in the class registry for matches. The menu will\n then return with a list of these matches.\n\n The second method is to click on the "Browse Zope Source" link. In the\n main window, you will see a directory listing with the root Zope 3\n modules. You can click on the module names to discover their content. If a\n class is found, it is represented as a bold entry in the list.\n\n The documentation contents of a class provides you with an incredible\n amount of information. Not only does it tell you about its base classes,\n implemented interfaces, attributes and methods, but it also lists the\n interface that requires a method or attribute to be implemented and the\n permissions required to access it.\n '

The description.

setup()

Setup module and class tree.

Interfaces

Interfaces for code browser

interface zope.app.apidoc.codemodule.interfaces.IAPIDocRootModule

Marker interface for utilities that represent class browser root modules.

The utilities will be simple strings, representing the modules Python dotted name.

interface zope.app.apidoc.codemodule.interfaces.IModuleDocumentation

Extends: zope.container.interfaces.IReadContainer

Representation of a Python module for documentation.

The items of the container are sub-modules and classes.

getDocString()

Return the doc string of the module.

getFileName()

Return the file name of the module.

getPath()

Return the Python path of the module.

isPackage()

Return true if this module is a Python package.

getDeclaration()

Return the interfaces provided by the module.

The returned value provides zope.interface.interfaces.IDeclaration. To get the list of interfaces, iterate over the returned value. The list will be empty if the module does not provide any interfaces.

interface zope.app.apidoc.codemodule.interfaces.IClassDocumentation

Representation of a class or type for documentation.

getDocString()

Return the doc string of the class.

getPath()

Return the Python path of the class.

getBases()

Return the base classes of the class.

getKnownSubclasses()

Return the known subclasses classes of the class.

getInterfaces()

Return the interfaces the class implements.

getAttributes()

Return a list of 3-tuple attribute information.

The first entry of the 3-tuple is the name of the attribute, the second is the attribute object itself. The third entry is the interface in which the attribute is defined.

Note that only public attributes are returned, meaning only attributes that do not start with an ‘_’-character.

getMethods()

Return a list of 3-tuple method information.

The first entry of the 3-tuple is the name of the method, the second is the method object itself. The third entry is the interface in which the method is defined.

Note that only public methods are returned, meaning only methods that do not start with an ‘_’-character.

getMethodDescriptors()

Return a list of 3-tuple method descriptor information.

The first entry of the 3-tuple is the name of the method, the second is the method descriptor object itself. The third entry is the interface in which the method is defined.

Note that only public methods are returned, meaning only method descriptors that do not start with an ‘_’-character.

getSecurityChecker()

Return the security checker for this class.

Since 99% of the time we are dealing with name-based security checkers, we can look up the get/set permission required for a particular class attribute/method.

getConstructor()

Return the __init__ method, or None if there isn’t one.

interface zope.app.apidoc.codemodule.interfaces.IFunctionDocumentation

Representation of a function for documentation.

getDocString()

Return the doc string of the function.

getPath()

Return the Python path of the function.

getSignature()

Return the signature of the function as a string.

getAttributes()

Return a list of 2-tuple attribute information.

The first entry of the 2-tuple is the name of the attribute, the second is the attribute object itself.

interface zope.app.apidoc.codemodule.interfaces.IDirective

Representation of a directive in IZCMLFile.

name

Name

Name of the directive in the form (Namespace. Name)

schema

Schema

Schema describing the directive attributes

attrs

Attributes

SAX parser representation of the directive’s attributes

context

Configuration Context

Configuration context while the directive was parsed.

prefixes

Prefixes

Mapping from namespace URIs to prefixes.

info

Info

ParserInfo objects containing line and column info.

__parent__

Parent

Parent Directive

subs

Sub-Directives

List of sub-directives

interface zope.app.apidoc.codemodule.interfaces.IRootDirective

Extends: zope.app.apidoc.codemodule.interfaces.IDirective

Marker interface

interface zope.app.apidoc.codemodule.interfaces.IZCMLFile

ZCML File Object

This is the main object that will manage the configuration of one particular ZCML configuration file.

filename

Configuration Filename

Path to the configuration file

package

Configuration Package

Specifies the package from which the configuration file will be

executed. If you do not specify the package, then the configuration cannot be fully validated and improper ZCML files might be written.

rootElement

XML Root Element

XML element representing the configuration root.

interface zope.app.apidoc.codemodule.interfaces.ITextFile

Text file object

path

Path

Path to the text file

getContent()

Return the content of the text file, in unicode

Classes

Class representation for code browser

class zope.app.apidoc.codemodule.class_.Class(module, name, klass)

Bases: object

This class represents a class declared in the module.

getPath()

See IClassDocumentation.

getDocString()

See IClassDocumentation.

getBases()

See IClassDocumentation.

getKnownSubclasses()

See IClassDocumentation.

getInterfaces()

See IClassDocumentation.

getAttributes()

See IClassDocumentation.

getMethods()

See IClassDocumentation.

getSecurityChecker()

See IClassDocumentation.

getConstructor()

See IClassDocumentation.

Functions

Function representation for code browser

class zope.app.apidoc.codemodule.function.Function(module, name, func, doc=None)

Bases: object

This class represents a function declared in the module.

getPath()

See IFunctionDocumentation.

getDocString()

See IFunctionDocumentation.

getSignature()

See IFunctionDocumentation.

getAttributes()

See IFunctionDocumentation.

Modules

Module representation for code browser

class zope.app.apidoc.codemodule.module.Module(parent, name, module, setup=True)

Bases: zope.app.apidoc.utilities.ReadContainerBase

This class represents a Python module.

Initialize object.

getDocString()

See IModuleDocumentation.

getFileName()

See IModuleDocumentation.

getPath()

See IModuleDocumentation.

isPackage()

See IModuleDocumentation.

getDeclaration()

See IModuleDocumentation.

get(key, default=None)

See zope.container.interfaces.IReadContainer.

items()

See zope.container.interfaces.IReadContainer.

Text

Function representation for code browser

class zope.app.apidoc.codemodule.text.TextFile(path, name, package)

Bases: object

This class represents a function declared in the module.

ZCML

ZCML File Representation

class zope.app.apidoc.codemodule.zcml.MyConfigHandler(context)

Bases: zope.configuration.xmlconfig.ConfigurationHandler, object

Special configuration handler to generate an XML tree.

class zope.app.apidoc.codemodule.zcml.Directive(name, schema, attrs, context, info, prefixes)

Bases: object

Representation of a ZCML directive.

class zope.app.apidoc.codemodule.zcml.ZCMLFile(filename, package, parent, name)

Bases: object

Representation of an entire ZCML file.

Configuration

This module handles the ‘apidoc:rootModule’ and ‘apidoc:moduleImport’ namespace directives.

zope.app.apidoc.codemodule.metaconfigure.rootModule(_context, module)

Register a new module as a root module for the class browser.

zope.app.apidoc.codemodule.metaconfigure.moduleImport(_context, allow)

Set the __import_unknown_modules__ flag

apidoc ZCML namespace directive interfaces

interface zope.app.apidoc.codemodule.metadirectives.IRootModule

Declares a new root module to be available for the class documentation module.

module

Root Module Name

This is the Python path of the new root module.

interface zope.app.apidoc.codemodule.metadirectives.IModuleImport

Set a flag whether new modules can be imported to the class registry or not.

allow

Allow Importing Modules

When set to true, new modules will be imported by path.

Browser

Class Views

class zope.app.apidoc.codemodule.browser.class_.ClassDetails

Bases: object

Represents the details of the class.

getBases()

Get all bases of this class.

getKnownSubclasses()

Get all known subclasses of this class.

getBaseURL()

Return the URL for the API Documentation Tool.

getInterfaces()

Get all implemented interfaces (as paths) of this class.

getAttributes()

Get all attributes of this class.

getMethods()

Get all methods of this class.

getDoc()

Get the doc string of the class STX formatted.

getConstructor()

Get info about the constructor, or None if there isn’t one.

Function Views

class zope.app.apidoc.codemodule.browser.function.FunctionDetails

Bases: object

Represents the details of the function.

getDocString()

Get the doc string of the function in a rendered format.

getAttributes()

Get all attributes of this function.

getBaseURL()

Return the URL for the API Documentation Tool.

Introspector view for content components

class zope.app.apidoc.codemodule.browser.introspector.annotationsNamespace(ob, request=None)

Bases: object

Used to traverse to the annotations of an object.

class zope.app.apidoc.codemodule.browser.introspector.sequenceItemsNamespace(ob, request=None)

Bases: object

Used to traverse to the values of a sequence.

class zope.app.apidoc.codemodule.browser.introspector.mappingItemsNamespace(ob, request=None)

Bases: object

Used to traverse to the values of a mapping.

Important: This might seem like overkill, but we do not know that (1) every mapping has a traverser and (2) whether the location is available. A location might not be available, if we have a mapping in the annotations, for example.

class zope.app.apidoc.codemodule.browser.introspector.Introspector(context, request)

Bases: zope.publisher.browser.BrowserView

Introspector browser view

Code Module Menu

class zope.app.apidoc.codemodule.browser.menu.Menu

Bases: object

Menu for the Class Documentation Module.

The menu allows for looking for classes by partial names. See findClasses() for the simple search implementation.

findClasses()

Find the classes that match a partial path.

Examples::

>>> from zope.app.apidoc.codemodule.class_ import Class

Setup the view.

>>> from zope.app.apidoc.codemodule.browser.menu import Menu
>>> from zope.publisher.browser import TestRequest
>>> menu = Menu()
>>> menu.context = apidoc['Code']

Testing the method with various inputs.

>>> menu.request = TestRequest(form={'path': 'menu'})
>>> info = menu.findClasses()

>>> from pprint import pprint
>>> pprint(info)
[{'path': 'zope.app.apidoc.codemodule.browser.menu.Men',
  'url': 'http://127.0.0.1/++apidoc++/Code/zope/app/apidoc/codemodule/browser/menu/Menu/'},
 {'path': 'zope.app.apidoc.ifacemodule.menu.Men',
  'url': 'http://127.0.0.1/++apidoc++/Code/zope/app/apidoc/ifacemodule/menu/Menu/'}...]

>>> menu.request = TestRequest(form={'path': 'illegal name'})
>>> info = menu.findClasses()
>>> pprint(info)
[]

findAllClasses()

Find all classes

Examples:

Setup the view.

>>> from zope.app.apidoc.codemodule.browser.menu import Menu
>>> from zope.publisher.browser import TestRequest
>>> menu = Menu()
>>> menu.context = apidoc['Code']

Make sure we're registered.

>>> traverse(menu.context, 'zope/app/apidoc/codemodule/browser/menu/Menu')
<zope.app.apidoc.codemodule.class_.Class object at ...>

Testing the method with various inputs.

>>> menu.request = TestRequest(form={'path': 'Foo'})
>>> info = menu.findAllClasses()

>>> info = [x for x in info if x['path'] == 'zope.app.apidoc.codemodule.browser.menu.Menu']
>>> len(info)
1

Module Views

zope.app.apidoc.codemodule.browser.module.formatDocString(text, module=None, summary=False)

Format a doc string for display.

module is either a Python module (from sys.modules) or the dotted name of a module.

If summary is true, the result is plain text and includes only the summary part of the doc string. If summary is false, the result is HTML and includes the whole doc string.

class zope.app.apidoc.codemodule.browser.module.ModuleDetails(context, request)

Bases: zope.publisher.browser.BrowserView

Represents the details of a module or package.

getDoc()

Get the doc string of the module, formatted as HTML.

getPath()

Return the path to the module

isPackage()

Return true if this module is a package

getModuleInterfaces()

Return entries about interfaces the module provides

getModules()

Return entries about contained modules and subpackages

getInterfaces()

Return entries about interfaces declared by the module

getClasses()

Return entries about classes declared by the module

getTextFiles()

Return entries about text files contained in the package

getZCMLFiles()

Return entries about ZCML files contained in the package

getFunctions()

Return entries about functions declared by the package

Browser utilities for API documentation.

class zope.app.apidoc.codemodule.browser.utilities.CodeBreadCrumbs

Bases: object

View that provides breadcrumbs for code objects

Function Views

class zope.app.apidoc.codemodule.browser.text.TextFileDetails

Bases: object

Represents the details of the text file.

renderedContent()

Render the file content to HTML.

ZCML Element Views

class zope.app.apidoc.codemodule.browser.zcml.DirectiveDetails

Bases: object

Details about ZCML directives.

Interfaces

Interface Documentation Module

The interface documentation module retrieves its information from the site manager. Therefore, currently there are no unregsitered interfaces listed in the documentation. This might be good, since unregistered interfaces are usually private and not of interest to a general developer.

interface zope.app.apidoc.ifacemodule.ifacemodule.IInterfaceModule

Extends: zope.app.apidoc.interfaces.IDocumentationModule

Interface API Documentation Module

This is a marker interface, so that we can write adapters for objects implementing this interface.

class zope.app.apidoc.ifacemodule.ifacemodule.InterfaceModule

Bases: zope.app.apidoc.utilities.DocumentationModuleBase

Represent the Documentation of all Interfaces.

The items of the container are all the interfaces listed in the global site manager.

title = u'Interfaces'

The title.

description = u'\n All used and important interfaces are registered through the site\n manager. While it would be possible to just list all attributes, it is\n hard on the user to read such an overfull list. Therefore, interfaces that\n have partial common module paths are bound together.\n\n The documentation of an interface also provides a wide variety of\n information, including of course the declared attributes/fields and\n methods, but also available adapters, and utilities that provide\n this interface.\n '

The description.

Interfaces

Interface Documentation Module Interfaces

interface zope.app.apidoc.ifacemodule.interfaces.IInterfaceDetailsPreferences

Preferences for API Docs’ Interface Details Screen

It is possible to hide and show various sections of the interface details’ screen. The following preferences allow you to choose the sections to be shown by default.

showSpecificRequiredAdapters

Specific Required Interface Adapters

Show specific required interface adapters

showExtendedRequiredAdapters

Extended Required Interface Adapters

Show extended required interface adapters

showGenericRequiredAdapters

Generic Required Interface Adapters

Show generic required interface adapters

showBrowserViews

Browser Views

Show browser views

showSpecificBrowserViews

Specific Browser Views

Show specific browser views

showExtendedBrowserViews

Extended Browser Views

Show extended browser views

showGenericBrowserViews

Generic Browser Views

Show generic browser views

showXMLRPCViews

XML-RPC Views

Show XML-RPC views

showSpecificXMLRPCViews

Specific XML-RPC Views

Show specific XML-RPC views

showExtendedXMLRPCViews

Extended XML-RPC Views

Show extended XML-RPC views

showGenericXMLRPCViews

Generic XML-RPC Views

Show generic XML-RPC views

showHTTPViews

Generic HTTP Views

Show generic HTTP views

showSpecificHTTPViews

Specific HTTP Views

Show specific HTTP views

showExtendedHTTPViews

Extended HTTP Views

Show extended HTTP views

showGenericHTTPViews

Generic HTTP Views

Show generic HTTP views

showFTPViews

FTP Views

Show FTP views

showSpecificFTPViews

Specific FTP Views

Show specific FTP views

showExtendedFTPViews

Extended FTP Views

Show extended FTP views

showGenericFTPViews

Generic FTP Views

Show generic FTP views

showOtherViews

Other Views

Show other (unidentified) views

showSpecificOtherViews

Specific Other Views

Show specific other views

showExtendedOtherViews

Extended Other Views

Show extended other views

showGenericOtherViews

Generic Other Views

Show generic other views

Browser

Interface Details View

class zope.app.apidoc.ifacemodule.browser.InterfaceDetails(context, request)

Bases: zope.publisher.browser.BrowserView

View class for an Interface.

getId()

Return the id of the field as it is defined for the interface utility.

Example:

>>> from tests import getInterfaceDetails
>>> details = getInterfaceDetails()
>>> details.getId()
'IFoo'

getDoc()

Return the main documentation string of the interface.

Example:

>>> from tests import getInterfaceDetails
>>> details = getInterfaceDetails()
>>> details.getDoc()[:55]
u'<div class="document">\n<p>This is the Foo interface</p>'

getBases()

Get all bases of this class

Example:

>>> from tests import getInterfaceDetails
>>> details = getInterfaceDetails()
>>> details.getBases()
['zope.interface.Interface']

getTypes()

Return a list of interface types that are specified for this interface.

getAttributes()

Return a list of attributes in the order they were specified.

getMethods()

Return a list of methods in the order they were specified.

getFields()

Return a list of fields in required + alphabetical order.

The required attributes are listed first, then the optional attributes.

getSpecificRequiredAdapters()

Get adapters where this interface is required.

getExtendedRequiredAdapters()

Get adapters where this interface is required.

getGenericRequiredAdapters()

Get adapters where this interface is required.

getProvidedAdapters()

Get adapters where this interface is provided.

getClasses()

Get the classes that implement this interface.

Example:

>>> from pprint import pprint
>>> from tests import getInterfaceDetails
>>> details = getInterfaceDetails()

>>> classes = details.getClasses()
>>> pprint(classes)
[[('path', 'zope.app.apidoc.ifacemodule.tests.Foo'),
  ('url', 'zope/app/apidoc/ifacemodule/tests/Foo')]]

getFactories()

Return the factories, who will provide objects implementing this interface.

getUtilities()

Return all utilities that provide this interface.

class zope.app.apidoc.ifacemodule.browser.InterfaceBreadCrumbs

Bases: object

View that provides breadcrumbs for interface objects

API Documentation macros

class zope.app.apidoc.ifacemodule.macros.InterfaceDetailsMacros(context, request)

Bases: zope.app.basicskin.standardmacros.StandardMacros

Page Template METAL macros for Interfaces

macro_pages = ('iface_macros', 'component_macros', 'presentation_macros')

Macro pages.

Interface Module Browser Menu (Tree)

zope.app.apidoc.ifacemodule.menu.getAllTextOfInterface(iface)

Get all searchable text from an interface

class zope.app.apidoc.ifacemodule.menu.Menu

Bases: object

Menu for the Interface Documentation Module.

findInterfaces()

Find the interface that match any text in the documentation strings or a partial path.

findAllInterfaces()

Find all interfaces.

Types

Interface Types Documentation Module

class zope.app.apidoc.typemodule.type.TypeInterface(interface, parent, name)

Bases: zope.app.apidoc.utilities.ReadContainerBase

Representation of the special type interface.

Demonstration:

>>> from zope.interface import Interface
>>> class IFoo(Interface):
...    pass
>>> class IDerivedFoo(IFoo):
...    pass
>>> from zope import component as ztapi
>>> ztapi.provideUtility(IDerivedFoo, IFoo, 'Foo')

>>> typeiface = TypeInterface(IFoo, None, None)
>>> typeiface.interface
<InterfaceClass zope.app.apidoc.typemodule.type.IFoo>

>>> typeiface.get('Foo').__class__
<class 'zope.interface.interface.InterfaceClass'>

>>> typeiface.items()
[(u'Foo', <InterfaceClass zope.app.apidoc.typemodule.type.IDerivedFoo>)]

get(key, default=None)

See zope.container.interfaces.IReadContainer

items()

See zope.container.interfaces.IReadContainer

class zope.app.apidoc.typemodule.type.TypeModule

Bases: zope.app.apidoc.utilities.DocumentationModuleBase

Represent the Documentation of all interface types.

Demonstration:

>>> class IFoo(IInterface):
...    pass

>>> from zope import component as ztapi
>>> ztapi.provideUtility(IFoo, IInterface, 'IFoo')

>>> module = TypeModule()
>>> type = module.get('IFoo')

>>> type.interface
<InterfaceClass zope.app.apidoc.typemodule.type.IFoo>

>>> [type.interface for name, type in module.items()]
[<InterfaceClass zope.app.apidoc.typemodule.type.IFoo>]

title = u'Interface Types'

Title

description = u'\n Here you can see all registered interface types. When you open the subtree\n of a specific interface type, you can see all the interfaces that provide\n this type. This can be very useful in cases where you want to determine\n all content type interfaces, for example.\n '

Description

Browser

Browser Views for Interface Types

class zope.app.apidoc.typemodule.browser.Menu

Bases: object

Menu View Helper Class

getMenuTitle(node)

Return the title of the node that is displayed in the menu.

getMenuLink(node)

Return the HTML link of the node that is displayed in the menu.

Utilities

Utility Documentation Module

zope.app.apidoc.utilitymodule.utilitymodule.encodeName(name)

Encode the name in URL safe base 64.

zope.app.apidoc.utilitymodule.utilitymodule.decodeName(name)

Decode the name as encoded by encodeName().

class zope.app.apidoc.utilitymodule.utilitymodule.Utility(parent, reg)

Bases: object

Representation of a utility for the API Documentation

Initialize Utility object.

class zope.app.apidoc.utilitymodule.utilitymodule.UtilityInterface(parent, name, interface)

Bases: zope.app.apidoc.utilities.ReadContainerBase

Representation of an interface a utility provides.

get(key, default=None)

See zope.container.interfaces.IReadContainer

items()

See zope.container.interfaces.IReadContainer

class zope.app.apidoc.utilitymodule.utilitymodule.UtilityModule

Bases: zope.app.apidoc.utilities.DocumentationModuleBase

Represent the Documentation of all Interfaces.

The items of the container are all utility interfaces registered in the site manager.

title = u'Utilities'

Title.

description = u'\n Utilities are also nicely registered in a site manager, so that it is easy\n to create a listing of available utilities. A utility is identified by the\n providing interface and a name, which can be empty. The menu provides you\n with a list of interfaces that utilities provide and as sub-items the\n names of the various implementations.\n\n Again, the documentation of a utility lists all the attributes/fields and\n methods the utility provides and provides a link to the implementation.\n '

Description.

Browser

Utility Module Views

class zope.app.apidoc.utilitymodule.browser.UtilityDetails

Bases: object

Utility Details View.

getName()

Get the name of the utility.

getInterface()

Return the interface the utility provides.

getComponent()

Return the python path of the implementation class.

class zope.app.apidoc.utilitymodule.browser.Menu

Bases: object

Menu View Helper Class

getMenuTitle(node)

Return the title of the node that is displayed in the menu.

getMenuLink(node)

Return the HTML link of the node that is displayed in the menu.

ZCML

ZCML Documentation module

The ZCML documentation module reads all of the meta directives (but does not execute them) and uses the collected data to generate the tree. The result of the evaluation is stored in thread-global variables, so that we have to parse the files only once.

zope.app.apidoc.zcmlmodule.quoteNS(ns)

Quotes a namespace to make it URL-secure.

zope.app.apidoc.zcmlmodule.unquoteNS(ns)

Un-quotes a namespace from a URL-secure version.

class zope.app.apidoc.zcmlmodule.Namespace(parent, name)

Bases: zope.app.apidoc.utilities.ReadContainerBase

Simple namespace object for the ZCML Documentation Module.

This container has Directive items as its values.

getShortName()

Get the short name of the namespace.

getFullName()

Get the full name of the namespace.

getQuotedName()

Get the full name, but quoted for a URL.

class zope.app.apidoc.zcmlmodule.Directive(ns, name, schema, handler, info, subdirs)

Bases: object

Represents a ZCML Directive.

class zope.app.apidoc.zcmlmodule.ZCMLModule

Bases: zope.app.apidoc.utilities.DocumentationModuleBase

Represent the Documentation of all ZCML namespaces.

The items of the container are tuples of globally known namespaces found in the appsetup config context.

title = u'ZCML Reference'

Title.

description = u'\n This module presents you with a complete list of ZCML directives and\n serves therefore well as reference. The menu provides you with a tree that\n organizes the directives by namespaces.\n\n The documentation contents for each directive tells you all the available\n attributes and their semantics. It also provides a link to the interface\n the directive confirms to. If available, it will even tell you the\n file the directive was declared in. At the end a list of available\n subdirectives is given, also listing the implemented interface and\n available attributes.\n '

Description.

get(key, default=None)

Get the namespace by name; long and abbreviated names work.

Browser

Browser Views for ZCML Reference

class zope.app.apidoc.zcmlmodule.browser.Menu

Bases: object

Menu View Helper Class

getMenuTitle(node)

Return the title of the node that is displayed in the menu.

getMenuLink(node)

Return the HTML link of the node that is displayed in the menu.

class zope.app.apidoc.zcmlmodule.browser.DirectiveDetails

Bases: object

View class for a Directive.

getSchema()

Return the schema of the directive.

getNamespaceName()

Return the name of the namespace.

getFileInfo()

Get the file where the directive was declared.

getInfo()

Get the file where the directive was declared.

getHandler()

Return information about the handler.

getSubdirectives()

Create a list of subdirectives.