[Zope3-checkins] CVS: Zope3/src/zope/app/apidoc/utilitymodule - __init__.py:1.1 browser.py:1.1 configure.zcml:1.1 index.pt:1.1 menu.pt:1.1 tests.py:1.1

Philipp von Weitershausen philikon at philikon.de
Thu Feb 19 15:46:43 EST 2004


Update of /cvs-repository/Zope3/src/zope/app/apidoc/utilitymodule
In directory cvs.zope.org:/tmp/cvs-serv13817/utilitymodule

Added Files:
	__init__.py browser.py configure.zcml index.pt menu.pt 
	tests.py 
Log Message:
Bring over zope.products.apidoc to zope.app.


=== Added File Zope3/src/zope/app/apidoc/utilitymodule/__init__.py ===
##############################################################################
#
# Copyright (c) 2004 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.0 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""Utility Documentation Module

$Id: __init__.py,v 1.1 2004/02/19 20:46:42 philikon Exp $
"""
from zope.interface import implements

from zope.app import zapi
from zope.app.interfaces.location import ILocation
from zope.app.apidoc.interfaces import IDocumentationModule
from zope.app.apidoc.utilities import ReadContainerBase, getPythonPath

__metaclass__ = type

# Constant used when the utility has no name
NONAME = '__noname__'

class Utility:
    """Representation of a utility for the API Documentation"""

    implements(ILocation)
    
    def __init__(self, parent, name, interface, component):
        self.__parent__ = parent
        self.__name__ = name or NONAME
        self.interface = interface
        self.component = component


class UtilityInterface(ReadContainerBase):
    r"""Representation of an interface a utility provides.

    Demonstration::

      >>> from zope.app.apidoc.utilitymodule import tests
      >>> from zope.app.apidoc.interfaces import IDocumentationModule
      >>> tests.setUp()

      >>> id = 'zope.app.apidoc.interfaces.IDocumentationModule'
      >>> ut_iface = UtilityInterface(UtilityModule(), id,
      ...                             IDocumentationModule) 

      >>> ut_iface.get('Classes').component.__class__.__name__
      'ClassModule'

      >>> ut_iface.get('').component.__class__.__name__
      'InterfaceModule'

      >>> ut_iface.get(NONAME).component.__class__.__name__
      'InterfaceModule'

      >>> ut_iface.get('foo') is None
      True

      >>> print '\n'.join([id for id, iface in ut_iface.items()])
      Classes
      __noname__
      
      >>> tests.tearDown()
    """

    implements(ILocation)

    def __init__(self, parent, name, interface):
        self.__parent__ = parent
        self.__name__ = name
        self.interface = interface

    def get(self, key, default=None):
        """See zope.app.interfaces.container.IReadContainer"""
        service = zapi.getService(self, 'Utilities')        
        if key == NONAME:
            key = ''
        util = service.queryUtility(self.interface, default, key)
        if util != default:
            util = Utility(self, key, self.interface, util)

        return util

    def items(self):
        """See zope.app.interfaces.container.IReadContainer"""
        service = zapi.getService(self, 'Utilities')
        items = service.getRegisteredMatching(self.interface)
        items = [(name or NONAME, self.get(name)) for iface, name, c in items]
        items.sort()
        return items


class UtilityModule(ReadContainerBase):
    r"""Represent the Documentation of all Interfaces.

    This documentation is implemented using a simply 'IReadContainer'. The
    items of the container are all factories listed in the closest
    factory service and above.

    Demonstration::

      >>> from zope.app.apidoc.utilitymodule import tests
      >>> tests.setUp()

      >>> module = UtilityModule()
      >>> ut_iface = module.get(
      ...     'zope.app.apidoc.interfaces.IDocumentationModule')

      >>> ut_iface.interface.getName()
      'IDocumentationModule'

      >>> print '\n'.join([id for id, iface in module.items()])
      zope.app.apidoc.interfaces.IDocumentationModule
      
      >>> tests.tearDown()
    """

    implements(IDocumentationModule)

    # See zope.app.apidoc.interfaces.IDocumentationModule
    title = 'Utilities'
    
    # See zope.app.apidoc.interfaces.IDocumentationModule
    description = """
    Utilities are also nicely registered in a service, so that it is easy to
    create a listing of available utilities. A utility is identified by the
    providing interface and a name, which can be empty. The menu provides you
    with a list of interfaces that utilities provide and as sub-items the
    names of the various implementations.

    Again, the documentation of a utility lists all the attributes/fields and
    methods the utility provides and provides a link to the implementation. 
    """
    
    def get(self, key, default=None):
        parts = key.split('.')
        try:
            mod = __import__('.'.join(parts[:-1]), {}, {}, ('*',))
        except ImportError:
            return default
        else:
            return UtilityInterface(self, key, getattr(mod, parts[-1], default))

    def items(self):
        service = zapi.getService(self, 'Utilities')
        matches = service.getRegisteredMatching()
        ifaces = {}
        for iface, name, c in matches:
            path = getPythonPath(iface)
            ifaces[path] = self.get(path)
        items = ifaces.items()
        items.sort()
        return items



=== Added File Zope3/src/zope/app/apidoc/utilitymodule/browser.py ===
##############################################################################
#
# Copyright (c) 2004 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.0 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""Utility Module Views

$Id: browser.py,v 1.1 2004/02/19 20:46:42 philikon Exp $
"""
from zope.app import zapi
from zope.app.location import LocationProxy
from zope.app.apidoc.ifacemodule.browser import InterfaceDetails
from zope.app.apidoc.utilities import getPythonPath
from zope.app.apidoc.utilitymodule import NONAME, Utility, UtilityInterface
from zope.proxy import removeAllProxies

__metaclass__ = type

class UtilityDetails:
    """Utility Details View."""

    def getName(self):
        """Get the name of the utility.

        Return the string "no name", if the utility has no name.
        """
        name = zapi.name(self.context)
        if name == NONAME:
            return 'no name'
        return name

    def getInterface(self):
        """Return the interface the utility provides.""" 
        schema = LocationProxy(self.context.interface,
                               self.context,
                               getPythonPath(self.context.interface))
        return InterfaceDetails(schema, self.request)

    def getComponent(self):
        """Return the python path of the implementation class."""
        if isinstance(self.context.component, (unicode, str)):
            return None #self.context.component
        return getPythonPath(self.context.component.__class__)

class Menu:
    """Menu View Helper Class

    A class that helps building the menu. The menu_macros expects the menu view
    class to have the getMenuTitle(node) and getMenuLink(node) methods
    implemented. 'node' is a 'zope.app.tree.node.Node' instance.
    """

    def getMenuTitle(self, node):
        """Return the title of the node that is displayed in the menu."""
        obj = removeAllProxies(node.context)
        if zapi.name(obj) == NONAME:
            return 'no name'
        if isinstance(obj, UtilityInterface):
            return zapi.name(obj).split('.')[-1]
        return zapi.name(obj)

    def getMenuLink(self, node):
        """Return the HTML link of the node that is displayed in the menu."""
        obj = removeAllProxies(node.context)
        if isinstance(obj, Utility):
            iface = zapi.getParent(obj)
            return './'+zapi.name(iface) + '/' + zapi.name(obj) + '/index.html'
        if isinstance(obj, UtilityInterface):
            return '../Interface/'+zapi.name(obj) + '/apiindex.html'
        return None


=== Added File Zope3/src/zope/app/apidoc/utilitymodule/configure.zcml ===
<configure
  xmlns="http://namespaces.zope.org/zope"
  xmlns:browser="http://namespaces.zope.org/browser">

  <class class=".UtilityModule">
    <allow interface="zope.app.apidoc.interfaces.IDocumentationModule" />
    <allow interface="zope.app.interfaces.container.IReadContainer" />
  </class>

  <class class=".Utility">
    <allow attributes="interface component" />
  </class>

  <class class=".UtilityInterface">
    <allow interface="zope.app.interfaces.container.IReadContainer" />
    <allow attributes="interface" />
  </class>

  <utility
      provides="zope.app.apidoc.interfaces.IDocumentationModule"
      factory=".UtilityModule"
      name="Utility" />

  <browser:page
      for=".UtilityModule"
      permission="zope.View"
      class=".browser.Menu"
      name="menu.html"
      template="menu.pt" />

  <browser:page
      for=".Utility"
      permission="zope.View"
      class=".browser.UtilityDetails"
      name="index.html"
      template="index.pt" />

</configure>


=== Added File Zope3/src/zope/app/apidoc/utilitymodule/index.pt ===
<html metal:use-macro="views/apidoc_macros/details">
<body metal:fill-slot="contents"
      tal:define="iface view/getInterface">

  <h1 class="details-header">
    <a href=""
       tal:attributes="href iface/getId"
       tal:content="iface/getId" /> <br />
    (Name: "<span tal:replace="view/getName" />")
  </h1>

  <div class="indent" tal:condition="view/getComponent">
    <h3>
      Component: 
      <a href=""
         tal:attributes="href 
             string:../../../Class/index.html?path=${view/getComponent}"
         tal:content="view/getComponent" /></h3>
  </div>

  <div class="indent">
    <div class="documentation" tal:content="structure iface/getDoc">
      Here is the doc string
    </div>
  </div>

  <h2 class="details-section">Attributes/Fields</h2>

  <div class="indent"
      tal:define="attributes iface/getAttributes;
                  fields iface/getFields">

  <ul class="attr-list" 
      tal:condition="python: attributes or fields">
  
    <li tal:repeat="attr attributes">
      <b><code tal:content="attr/name">attr</code></b> (Attribute)<br>
      <div class="inline-documentation" tal:content="structure attr/doc">
        attr desc
      </div>      
    </li>

    <li tal:repeat="field fields">
      <b><code tal:content="field/name">field</code></b>
      - <a href=""
           tal:attributes="href string:../${field/iface/id}/apiindex.html">
          <code tal:content="field/iface/name">IField</code></a>
      (<span tal:content="string:${field/required}, ">optional, </span>
        default = <code tal:content="field/default" />)<br>
      <span tal:content="field/description">field desc</span>      
    </li>

  </ul>

  <p tal:condition="python: not (attributes or fields)">
    <em>There are no attributes or fields specified.</em>
  </p>

  </div>



  <h2 class="details-section">Methods</h2>

  <div class="indent"
       tal:define="methods iface/getMethods">

  <ul class="attr-list" tal:condition="methods">
    <li tal:repeat="method methods">
      <b><code 
          tal:content="string:${method/name}${method/signature}" />
      </b><br>
      <div class="inline-documentation" tal:content="structure method/doc">
        method desc
      </div>      
    </li>
  </ul>

  <p tal:condition="not: methods">
    <em>There are no methods or fields specified.</em>
  </p>

  </div>


</body>
</html>

=== Added File Zope3/src/zope/app/apidoc/utilitymodule/menu.pt ===
<html metal:use-macro="views/apidoc_macros/menu">
<body>

</body>
</html>

=== Added File Zope3/src/zope/app/apidoc/utilitymodule/tests.py ===
##############################################################################
#
# Copyright (c) 2004 Zope Corporation and Contributors.
# All Rights Reserved.
#
# This software is subject to the provisions of the Zope Public License,
# Version 2.0 (ZPL).  A copy of the ZPL should accompany this distribution.
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
# FOR A PARTICULAR PURPOSE.
#
##############################################################################
"""Tests for the Utility Documentation Module

$Id: tests.py,v 1.1 2004/02/19 20:46:42 philikon Exp $
"""
import unittest

from zope.interface import implements
from zope.testing.doctestunit import DocTestSuite

from zope.app import zapi
from zope.app.interfaces.traversing import IContainmentRoot
from zope.app.location import LocationProxy
from zope.app.tests import placelesssetup

from zope.app.apidoc.ifacemodule import InterfaceModule
from zope.app.apidoc.classmodule import ClassModule
from zope.app.apidoc.interfaces import IDocumentationModule


def setUp():
    placelesssetup.setUp()
    service = zapi.getService(None, 'Utilities')
    service.provideUtility(IDocumentationModule, InterfaceModule(), '')
    service.provideUtility(IDocumentationModule, ClassModule(), 'Classes')

def tearDown():
    placelesssetup.tearDown()


class Root:
    implements(IContainmentRoot)

    __parent__ = None
    __name__ = ''

def rootLocation(obj, name):
    return LocationProxy(obj, Root(), name)
    
def test_suite():
    return unittest.TestSuite((
        DocTestSuite('zope.app.apidoc.utilitymodule'),
        ))

if __name__ == '__main__':
    unittest.main()




More information about the Zope3-Checkins mailing list