Added correct header, change svn props

browser/__init__.py

@@ -0,0 +1,17 @@
+##############################################################################
+#
+# Copyright (c) 2004 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (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.
+#
+##############################################################################
+"""Security Views
+
+$Id:$
+"""

browser/authutilitysearchview.txt

@@ -0,0 +1,62 @@
+The Query View for Authentication Utilities
+===========================================
+
+A regular authentication service will not provide the `ISourceQueriables`
+interface, but it is a queriable itself, since it provides the simple
+`getPrincipals(name)` method:
+
+  >>> class Principal:
+  ...     def __init__(self, id): 
+  ...         self.id = id
+
+  >>> class MyAuthUtility:
+  ...     data = {'jim': Principal(42), 'don': Principal(0), 
+  ...             'stephan': Principal(1)}
+  ...
+  ...     def getPrincipals(self, name):
+  ...         return [principal
+  ...                 for id, principal in self.data.items()
+  ...                 if name in id]
+
+Now that we have our queriable, we create the view for it:
+
+  >>> from zope.app.security.browser.auth import AuthUtilitySearchView
+  >>> from zope.publisher.browser import TestRequest
+  >>> request = TestRequest()
+  >>> view = AuthUtilitySearchView(MyAuthUtility(), request)
+
+This allows us to render a search form.
+
+  >>> print view.render('test') # doctest: +NORMALIZE_WHITESPACE
+  <div class="row">
+  <div class="label">
+  Search String
+  </div>
+  <div class="field">
+  <input type="text" name="test.searchstring" />
+  </div>
+  </div>
+  <br /><input type="submit" name="test.search" value="Search" />
+
+If we ask for results:
+
+  >>> view.results('test')
+
+We don't get any, since we did not provide any. But if we give input:
+
+  >>> request.form['test.searchstring'] = 'n'
+
+we still don't get any:
+
+  >>> view.results('test')
+
+because we did not press the button. So let's press the button:
+
+  >>> request.form['test.search'] = 'Search'
+
+so that we now get results (!):
+
+  >>> ids = list(view.results('test'))
+  >>> ids.sort()
+  >>> ids
+  [0, 1]

browser/principalterms.py

@@ -0,0 +1,55 @@
+##############################################################################
+#
+# Copyright (c) 2004 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (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.
+#
+##############################################################################
+"""Terms view for Principal Source
+
+$Id$
+"""
+__docformat__ = "reStructuredText"
+
+from zope.interface import implements
+from zope.publisher.interfaces.browser import IBrowserRequest
+
+from zope.app import zapi
+from zope.app.form.browser.interfaces import ITerms
+from zope.app.security.interfaces import IPrincipalSource
+
+class Term(object):
+
+    def __init__(self, token, title):
+        self.token = token
+        self.title = title
+
+
+class PrincipalTerms(object):
+    implements(ITerms)
+    __used_for__ = IPrincipalSource, IBrowserRequest
+
+    def __init__(self, context, request):
+        self.context = context
+
+    def getTerm(self, principal_id):
+        if principal_id not in self.context:
+            raise LookupError, principal_id
+
+        auth = zapi.principals()
+        principal = auth.getPrincipal(principal_id)
+
+        if principal is None:
+            raise LookupError, principal_id
+
+        return Term(principal_id.encode('base64').strip().replace('=', '_'),
+                    principal.title)
+
+    def getValue(self, token):
+        return token.replace('_', '=').decode('base64')

browser/principalterms.txt

@@ -0,0 +1,67 @@
+Principal Terms
+===============
+
+Principal Terms are used to support browser interfaces for searching principal
+sources. They provide access to tokens and titles for values. The principal
+terms view uses an authentication utility to get principal titles. Let's
+create an authentication utility to demonstrate how this works:
+
+  >>> class Principal:
+  ...     def __init__(self, id, title):
+  ...         self.id, self.title = id, title
+
+  >>> from zope.interface import implements
+  >>> from zope.app.security.interfaces import IAuthenticationUtility
+  >>> from zope.app.security.interfaces import PrincipalLookupError
+  >>> class AuthUtility:
+  ...     implements(IAuthenticationUtility)
+  ...     data = {'jim': 'Jim Fulton', 'stephan': 'Stephan Richter'}
+  ...
+  ...     def getPrincipal(self, id):
+  ...         title = self.data.get(id)
+  ...         if title is not None:
+  ...             return Principal(id, title)
+  ...         raise PrincipalLookupError
+
+Now we need to install the authentication utility:
+
+  >>> from zope.app.tests import ztapi
+  >>> ztapi.provideUtility(IAuthenticationUtility, AuthUtility())
+
+We need a principal source so that we can create a view from it.
+
+  >>> from zope.app import zapi
+  >>> class PrincipalSource:
+  ...     def __contains__(self, id):
+  ...          auth = zapi.getUtility(IAuthenticationUtility)
+  ...          try:
+  ...              auth.getPrincipal(id)
+  ...          except PrincipalLookupError:
+  ...              return False
+  ...          else:
+  ...              return True
+
+Now we can create an terms view:
+
+  >>> from zope.app.security.browser.principalterms import PrincipalTerms
+  >>> terms = PrincipalTerms(PrincipalSource(), None)
+
+Now we can ask the terms view for terms:
+
+  >>> term = terms.getTerm('stephan')
+  >>> term.title
+  'Stephan Richter'
+  >>> term.token
+  'c3RlcGhhbg__'
+
+If we ask for a term that does not exist, we get a lookup error:
+
+  >>> terms.getTerm('bob')
+  Traceback (most recent call last):
+  ...
+  LookupError: bob
+
+If we have a token, we can get the principal id for it.
+
+  >>> terms.getValue('c3RlcGhhbg__')
+  'stephan'

browser/tests.py

@@ -0,0 +1,35 @@
+##############################################################################
+#
+# Copyright (c) 2004 Zope Corporation and Contributors.
+# All Rights Reserved.
+#
+# This software is subject to the provisions of the Zope Public License,
+# Version 2.1 (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.
+#
+##############################################################################
+"""Security Views Tests
+
+$Id$
+"""
+__docformat__ = "reStructuredText"
+import unittest
+from zope.testing import doctest
+from zope.app.tests import placelesssetup
+
+def test_suite():
+    return unittest.TestSuite((
+        doctest.DocFileSuite('authutilitysearchview.txt',
+                             setUp=placelesssetup.setUp,
+                             tearDown=placelesssetup.tearDown),
+        doctest.DocFileSuite('principalterms.txt',
+                             setUp=placelesssetup.setUp,
+                             tearDown=placelesssetup.tearDown),
+        ))
+
+if __name__ == '__main__':
+    unittest.main(defaultTest='test_suite')
+