[Zope-Checkins] CVS: Zope3/lib/python/Zope/Security - IChecker.py:1.1.2.2

[Jim Fulton]

Update of /cvs-repository/Zope3/lib/python/Zope/Security
In directory cvs.zope.org:/tmp/cvs-serv23422

Modified Files:
      Tag: SecurityProxy-branch
	IChecker.py 
Log Message:
check_* methods now raise exceptions when access is not allowed.


=== Zope3/lib/python/Zope/Security/IChecker.py 1.1.2.1 => 1.1.2.2 ===
         """Check whether attribute access is allowed
 
-        Returns None or a non-None boolean value. None means we don't
-        know. In this case, the caller should do the attribute access
-        and call checkValue with the value and a false value::
+        If access is not allowed, then an exception is raised.
+        if access is (possibly) allowed, then a boolean value is
+        returned. The value is true if accessed was allowed based on
+        the name, or false if access depends on the value. This
+        boolean value should be passed to checkValue:
 
+           allowed = checker.check_getattr(ob, name)
            v = getattr(ob, name)
            v = Wrapper(v, ob, name=name)
-           v = checkValue(v, 0)
-           return v
-
-        If a non-None false value is returned, then access should be
-        denied.
-
-        If a true value is returned, then the attribute access should
-        be performed and the attribute value should be passed to
-        checkValue along with a true value::
-
-           v = getattr(ob, name)
-           v = Wrapper(v, ob, name=name)
-           v = checkValue(v, 1)
-           return v
+           return checkValue(v, allowed)
 
         """
 
     def check_getitem(ob, key):
         """Check whether an item access is allowed
 
-        Return a boolean value indicating whether access is allowed.
+        An exception is raised if access is not allowed, otherwise,
+        nothing is returned. After checking the operation, the return
+        value should be passed to checkValue.
+
+           checker.check_getitem(ob, key)
+           return checkValue(ob[key])
+        
         """
 
-    def checkValue(value, allowed_by_default):
+    def checkValue(value, allowed_by_default=1):
         """Check access to a value
 
         The value must have a __permission__ attribute unless