← Back to branch summary

~hardware-certification/zope3/certify-staging-2.5

« back to all changes in this revision

Viewing changes to src/zope/app/apidoc/zcmlmodule/.svn/text-base/__init__.py.svn-base

  • Committer: Marc Tardif
  • Date: 2008-04-26 19:03:34 UTC
  • Revision ID: cr3@lime-20080426190334-u16xo4llz56vliqf
Initial import.

Show diffs side-by-side

added added

removed removed

Lines of Context:
src/zope/app/apidoc/zcmlmodule/.svn/text-base/__init__.py.svn-base
 
1
##############################################################################
 
2
#
 
3
# Copyright (c) 2004 Zope Corporation and Contributors.
 
4
# All Rights Reserved.
 
5
#
 
6
# This software is subject to the provisions of the Zope Public License,
 
7
# Version 2.1 (ZPL).  A copy of the ZPL should accompany this distribution.
 
8
# THIS SOFTWARE IS PROVIDED "AS IS" AND ANY AND ALL EXPRESS OR IMPLIED
 
9
# WARRANTIES ARE DISCLAIMED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 
10
# WARRANTIES OF TITLE, MERCHANTABILITY, AGAINST INFRINGEMENT, AND FITNESS
 
11
# FOR A PARTICULAR PURPOSE.
 
12
#
 
13
##############################################################################
 
14
"""ZCML Documentation module
 
15
 
 
16
The ZCML documentation module reads all of the meta directives (but does not
 
17
execute them) and uses the collected data to generate the tree. The result of
 
18
the evaluation is stored in thread-global variables, so that we have to parse
 
19
the files only once.
 
20
 
 
21
$Id$
 
22
"""
 
23
__docformat__ = 'restructuredtext'
 
24
 
 
25
from zope.configuration import docutils, xmlconfig
 
26
from zope.i18nmessageid import ZopeMessageFactory as _
 
27
from zope.interface import implements
 
28
from zope.location.interfaces import ILocation
 
29
 
 
30
import zope.app.appsetup.appsetup
 
31
from zope.app.apidoc.interfaces import IDocumentationModule
 
32
from zope.app.apidoc.utilities import ReadContainerBase
 
33
 
 
34
# Caching variables, so that the meta-ZCML files need to be read only once
 
35
namespaces = None
 
36
subdirs = None
 
37
 
 
38
def quoteNS(ns):
 
39
    """Quotes a namespace to make it URL-secure."""
 
40
    ns = ns.replace(':', '_co_')
 
41
    ns = ns.replace('/', '_sl_')
 
42
    return ns
 
43
 
 
44
def unquoteNS(ns):
 
45
    """Un-quotes a namespace from a URL-secure version."""
 
46
    ns = ns.replace('_sl_', '/')
 
47
    ns = ns.replace('_co_', ':')
 
48
    return ns
 
49
 
 
50
 
 
51
class Namespace(ReadContainerBase):
 
52
    """Simple namespace object for the ZCML Documentation Module."""
 
53
 
 
54
    implements(ILocation)
 
55
 
 
56
    def __init__(self, parent, name):
 
57
        self.__parent__ = parent
 
58
        self.__realname__ = name
 
59
        self.__name__ = self.getQuotedName()
 
60
 
 
61
    def getShortName(self):
 
62
        """Get the short name of the namespace."""
 
63
        name = self.__realname__
 
64
        if name.startswith('http://namespaces.zope.org/'):
 
65
            name = name[27:]
 
66
        return name
 
67
 
 
68
    def getFullName(self):
 
69
        """Get the full name of the namespace."""
 
70
        return self.__realname__
 
71
 
 
72
    def getQuotedName(self):
 
73
        """Get the full name, but quoted for a URL."""
 
74
        name = self.getFullName()
 
75
        name = quoteNS(name)
 
76
        return name
 
77
 
 
78
    def get(self, key, default=None):
 
79
        """See zope.app.container.interfaces.IReadContainer"""
 
80
        ns = self.getFullName()
 
81
        if not namespaces[ns].has_key(key):
 
82
            return default
 
83
        schema, handler, info = namespaces[ns][key]
 
84
        sd = subdirs.get((ns, key), [])
 
85
        directive = Directive(self, key, schema, handler, info, sd)
 
86
        return directive
 
87
 
 
88
    def items(self):
 
89
        """See zope.app.container.interfaces.IReadContainer"""
 
90
        list = []
 
91
        for key in namespaces[self.getFullName()].keys():
 
92
            list.append((key, self.get(key)))
 
93
        list.sort()
 
94
        return list
 
95
 
 
96
 
 
97
class Directive(object):
 
98
    """Represents a ZCML Directive."""
 
99
 
 
100
    implements(ILocation)
 
101
 
 
102
    def __init__(self, ns, name, schema, handler, info, subdirs):
 
103
        self.__parent__ = ns
 
104
        self.__name__ = name
 
105
        self.schema = schema
 
106
        self.handler = handler
 
107
        self.info = info
 
108
        self.subdirs = subdirs
 
109
 
 
110
 
 
111
class ZCMLModule(ReadContainerBase):
 
112
    r"""Represent the Documentation of all ZCML namespaces.
 
113
 
 
114
    This documentation is implemented using a simple `IReadContainer`. The
 
115
    items of the container."""
 
116
 
 
117
    implements(IDocumentationModule)
 
118
 
 
119
    # See zope.app.apidoc.interfaces.IDocumentationModule
 
120
    title = _('ZCML Reference')
 
121
 
 
122
    # See zope.app.apidoc.interfaces.IDocumentationModule
 
123
    description = _("""
 
124
    This module presents you with a complete list of ZCML directives and
 
125
    serves therefore well as reference. The menu provides you with a tree that
 
126
    organizes the directives by namespaces.
 
127
 
 
128
    The documentation contents for each directive tells you all the available
 
129
    attributes and their semantics. It also provides a link to the interface
 
130
    the directive confirms to. If available, it will even tell you the
 
131
    file the directive was declared in. At the end a list of available
 
132
    subdirectives is given, also listing the implemented interface and
 
133
    available attributes.
 
134
    """)
 
135
 
 
136
    def _makeDocStructure(self):
 
137
        # Some trivial caching
 
138
        global namespaces
 
139
        global subdirs
 
140
        context = zope.app.appsetup.appsetup.getConfigContext()
 
141
        namespaces, subdirs = docutils.makeDocStructures(context)
 
142
 
 
143
        # Empty keys are not so good for a container
 
144
        if namespaces.has_key(''):
 
145
            namespaces['ALL'] = namespaces['']
 
146
            del namespaces['']
 
147
 
 
148
 
 
149
    def get(self, key, default=None):
 
150
        """See zope.app.container.interfaces.IReadContainer
 
151
 
 
152
        Get the namespace by name; long and abbreviated names work.
 
153
        """
 
154
        if namespaces is None or subdirs is None:
 
155
            self._makeDocStructure()
 
156
 
 
157
        key = unquoteNS(key)
 
158
        if namespaces.has_key(key):
 
159
            return Namespace(self, key)
 
160
 
 
161
        full_key = 'http://namespaces.zope.org/' + key
 
162
        if namespaces.has_key(full_key):
 
163
            return Namespace(self, full_key)
 
164
 
 
165
        return default
 
166
 
 
167
 
 
168
    def items(self):
 
169
        """See zope.app.container.interfaces.IReadContainer"""
 
170
        if namespaces is None or subdirs is None:
 
171
            self._makeDocStructure()
 
172
        list = []
 
173
        for key in namespaces.keys():
 
174
            namespace = Namespace(self, key)
 
175
            # We need to make sure that we use the quoted URL as key
 
176
            list.append((namespace.getQuotedName(), namespace))
 
177
        list.sort()
 
178
        return list
 
179
 
 
180
 
 
181
def _clear():
 
182
    global namespaces
 
183
    global subdirs
 
184
    namespaces = None
 
185
    subdirs = None
 
186
 
 
187
from zope.testing.cleanup import addCleanUp
 
188
addCleanUp(_clear)