launchpad-reviewers team mailing list archive

[Colin Watson <mp+414409@xxxxxxxxxxxxxxxxxx>]

Colin Watson has proposed merging ~cjwatson/launchpad:expand-security-docs into launchpad:master.

Commit message:
Explain the various ZCML permission directives

Requested reviews:
  Launchpad code reviewers (launchpad-reviewers)

For more details, see:
https://code.launchpad.net/~cjwatson/launchpad/+git/launchpad/+merge/414409

`zope.security`'s documentation doesn't do a great job here, so explain the bits that we use heavily.
-- 
Your team Launchpad code reviewers is requested to review the proposed merge of ~cjwatson/launchpad:expand-security-docs into launchpad:master.

diff --git a/doc/security.rst b/doc/security.rst
index c80dba8..f4309af 100644
--- a/doc/security.rst
+++ b/doc/security.rst
@@ -80,3 +80,34 @@ In this example, the ``EditByOwner`` adapter's ``checkAuthenticated`` method
 will be called to determine if the currently authenticated user is
 authorized to access whatever is protected by ``launchpad.Edit`` on an
 ``IProduct``.
+
+The available permission directives are not well-documented by
+``zope.security``, so here's a summary:
+
+``<allow interface="..."/>``
+    The attributes and methods of this class that appear in the listed
+    interface may be publicly accessed.
+
+``<allow attributes="..."/>``
+    The named attributes and methods of this class may be publicly accessed.
+
+``<require permission="..." interface="..."/>``
+    The attributes and methods of this class that appear in the listed
+    interface may be accessed by users with the given permission.
+
+``<require permission="..." attributes="..."/>``
+    The named attributes and methods of this class may be accessed by users
+    with the given permission.
+
+``<require permission="..." set_schema="..."/>``
+    The attributes of this class that appear in the listed interface may be
+    modified by users with the given permission.
+
+``<require permission="..." set_attributes="..."/>``
+    The named attributes of this class may be modified by users with the
+    given permission.
+
+Note that "accessed" means ``getattr()``, while "modified" means
+``setattr()``.  The process of calling a method starts by using ``getattr()``
+to fetch the method from the object, so methods should be declared in
+``interface`` or ``attributes`` even if they modify the object.