Convert module checker doctests to Sphinx.

1 files changed, 166 insertions, 0 deletions

diff --git a/docs/api/checker.rst b/docs/api/checker.rst
index 1010e83..5072caa 100644
--- a/docs/api/checker.rst
+++ b/docs/api/checker.rst
@@ -5,6 +5,172 @@
    :members:
    :member-order: bysource
 
+
+Protections for Modules
+-----------------------
+
+The :func:`zope.secuirty.checker.moduleChecker` API can be used to
+determine whether a module has been protected: Initially, there's no checker
+defined for the module:
+
+.. doctest::
+
+   >>> from zope.security.checker import moduleChecker
+   >>> from zope.security.tests import test_directives
+   >>> moduleChecker(test_directives) is None
+   True
+
+We can add a checker using :func:`zope.security.metaconfigure.protectModule`:
+
+.. doctest::
+
+   >>> from zope.component import provideUtility
+   >>> from zope.security.metaconfigure import protectModule
+   >>> from zope.security.permission import Permission
+   >>> from zope.security.interfaces import IPermission
+   >>> TEST_PERM = 'zope.security.metaconfigure.test'
+   >>> perm = Permission(TEST_PERM, '')
+   >>> provideUtility(perm, IPermission, TEST_PERM)
+   >>> protectModule(test_directives, 'foo', TEST_PERM)
+
+Now, the checker should exist and have an access dictionary with the
+name and permission:
+
+.. doctest::
+
+   >>> def pprint(ob, width=70):
+   ...     from pprint import PrettyPrinter
+   ...     PrettyPrinter(width=width).pprint(ob)
+   >>> checker = moduleChecker(test_directives)
+   >>> cdict = checker.get_permissions
+   >>> pprint(cdict)
+   {'foo': 'zope.security.metaconfigure.test'}
+   
+   If we define additional names, they will be added to the dict:
+
+   >>> protectModule(test_directives, 'bar', TEST_PERM)
+   >>> protectModule(test_directives, 'baz', TEST_PERM)
+   >>> pprint(cdict)
+   {'bar': 'zope.security.metaconfigure.test',
+    'baz': 'zope.security.metaconfigure.test',
+    'foo': 'zope.security.metaconfigure.test'}
+        
+The allow directive creates actions for each named defined
+directly, or via interface:
+
+.. doctest::
+
+   >>> from zope.interface import Interface
+   >>> from zope.interface import Attribute
+   >>> from zope.security.metaconfigure import allow
+   >>> class I1(Interface):
+   ...     def x(): pass
+   ...     y = Attribute("Y")
+   >>> class I2(I1):
+   ...     def a(): pass
+   ...     b = Attribute("B")
+   >>> class AContext(object):
+   ...     def __init__(self):
+   ...         self.actions = []
+   ...
+   ...     def action(self, discriminator, callable, args):
+   ...         self.actions.append(
+   ...             {'discriminator': discriminator,
+   ...              'callable': int(callable is protectModule),
+   ...              'args': args})
+   ...     module='testmodule'
+
+   >>> context = AContext()
+   >>> allow(context, attributes=['foo', 'bar'], interface=[I1, I2])
+   >>> context.actions.sort(
+   ...    lambda a, b: cmp(a['discriminator'], b['discriminator']))
+   >>> pprint(context.actions)
+   [{'args': ('testmodule', 'a', 'zope.Public'),
+     'callable': 1,
+     'discriminator': ('http://namespaces.zope.org/zope:module',
+                       'testmodule',
+                       'a')},
+    {'args': ('testmodule', 'b', 'zope.Public'),
+     'callable': 1,
+     'discriminator': ('http://namespaces.zope.org/zope:module',
+                       'testmodule',
+                       'b')},
+    {'args': ('testmodule', 'bar', 'zope.Public'),
+     'callable': 1,
+     'discriminator': ('http://namespaces.zope.org/zope:module',
+                       'testmodule',
+                       'bar')},
+    {'args': ('testmodule', 'foo', 'zope.Public'),
+     'callable': 1,
+     'discriminator': ('http://namespaces.zope.org/zope:module',
+                       'testmodule',
+                       'foo')},
+    {'args': ('testmodule', 'x', 'zope.Public'),
+     'callable': 1,
+     'discriminator': ('http://namespaces.zope.org/zope:module',
+                       'testmodule',
+                       'x')},
+    {'args': ('testmodule', 'y', 'zope.Public'),
+     'callable': 1,
+     'discriminator': ('http://namespaces.zope.org/zope:module',
+                       'testmodule',
+                       'y')}]
+
+The provide directive creates actions for each named defined
+directly, or via interface:
+
+.. doctest::
+
+   >>> from zope.security.metaconfigure import require
+   >>> class RContext(object):
+   ...     def __init__(self):
+   ...         self.actions = []
+   ...     def action(self, discriminator, callable, args):
+   ...         self.actions.append(
+   ...             {'discriminator': discriminator,
+   ...              'callable': int(callable is protectModule),
+   ...              'args': args})
+   ...     module='testmodule'
+
+   >>> context = RContext()
+   >>> require(context, attributes=['foo', 'bar'],
+   ...         interface=[I1, I2], permission='p')
+
+   >>> context.actions.sort(
+   ...    lambda a, b: cmp(a['discriminator'], b['discriminator']))
+   >>> pprint(context.actions)
+   [{'args': ('testmodule', 'a', 'p'),
+     'callable': 1,
+     'discriminator': ('http://namespaces.zope.org/zope:module',
+                       'testmodule',
+                       'a')},
+    {'args': ('testmodule', 'b', 'p'),
+     'callable': 1,
+     'discriminator': ('http://namespaces.zope.org/zope:module',
+                       'testmodule',
+                       'b')},
+    {'args': ('testmodule', 'bar', 'p'),
+     'callable': 1,
+     'discriminator': ('http://namespaces.zope.org/zope:module',
+                       'testmodule',
+                       'bar')},
+    {'args': ('testmodule', 'foo', 'p'),
+     'callable': 1,
+     'discriminator': ('http://namespaces.zope.org/zope:module',
+                       'testmodule',
+                       'foo')},
+    {'args': ('testmodule', 'x', 'p'),
+     'callable': 1,
+     'discriminator': ('http://namespaces.zope.org/zope:module',
+                       'testmodule',
+                       'x')},
+    {'args': ('testmodule', 'y', 'p'),
+     'callable': 1,
+     'discriminator': ('http://namespaces.zope.org/zope:module',
+                       'testmodule',
+                       'y')}]
+
+
 Protections for set objects
 ---------------------------