From 6b180cbb77d6c5bee0e75220d93fc1800d1217df Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@plope.com>
Date: Wed, 15 Aug 2012 22:49:59 -0400
Subject: [PATCH] - An ``add_permission`` directive method was added to the
 Configurator.  This   directive registers a free-standing permission
 introspectable into the   Pyramid introspection system.  Frameworks built
 atop Pyramid can thus use   the the ``permissions`` introspectable category
 data to build a   comprehensive list of permissions supported by a running
 system.  Before   this method was added, permissions were already registered
 in this   introspectable category as a side effect of naming them in an
 ``add_view``   call, this method just makes it possible to arrange for a
 permission to be   put into the ``permissions`` introspectable category
 without naming it   along with an associated view.  Here's an example of
 usage of   ``add_permission``::

      config = Configurator()
      config.add_permission('view')
---
 CHANGES.txt                                | 15 +++++++++++++++
 docs/api/config.rst                        |  1 +
 pyramid/config/security.py                 | 20 ++++++++++++++++++++
 pyramid/tests/test_config/test_security.py |  9 +++++++++
 4 files changed, 45 insertions(+)

diff --git a/CHANGES.txt b/CHANGES.txt
index e092b15453..f02925585f 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -85,3 +85,18 @@ Features
 - When there is a predicate mismatch exception (seen when no view matches for
   a given request due to predicates not working), the exception now contains
   a textual description of the predicate which didn't match.
+
+- An ``add_permission`` directive method was added to the Configurator.  This
+  directive registers a free-standing permission introspectable into the
+  Pyramid introspection system.  Frameworks built atop Pyramid can thus use
+  the the ``permissions`` introspectable category data to build a
+  comprehensive list of permissions supported by a running system.  Before
+  this method was added, permissions were already registered in this
+  introspectable category as a side effect of naming them in an ``add_view``
+  call, this method just makes it possible to arrange for a permission to be
+  put into the ``permissions`` introspectable category without naming it
+  along with an associated view.  Here's an example of usage of
+  ``add_permission``::
+
+      config = Configurator()
+      config.add_permission('view')
diff --git a/docs/api/config.rst b/docs/api/config.rst
index bc9e067b1c..1b887988a3 100644
--- a/docs/api/config.rst
+++ b/docs/api/config.rst
@@ -36,6 +36,7 @@
      .. automethod:: set_authentication_policy
      .. automethod:: set_authorization_policy
      .. automethod:: set_default_permission
+     .. automethod:: add_permission
 
    :methodcategory:`Setting Request Properties`
 
diff --git a/pyramid/config/security.py b/pyramid/config/security.py
index e8ef1518da..567999cc47 100644
--- a/pyramid/config/security.py
+++ b/pyramid/config/security.py
@@ -137,3 +137,23 @@ def register():
                     introspectables=(intr, perm_intr,))
 
 
+    def add_permission(self, permission_name):
+        """
+        A configurator directive which registers a free-standing
+        permission without associating it with a view callable.  This can be
+        used so that the permission shows up in the introspectable data under
+        the ``permissions`` category (permissions mentioned via ``add_view``
+        already end up in there).  For example::
+
+          config = Configurator()
+          config.add_permission('view')
+        """
+        intr = self.introspectable(
+            'permissions',
+            permission_name,
+            permission_name,
+            'permission'
+            )
+        intr['value'] = permission_name
+        self.action(None, introspectables=(intr,))
+
diff --git a/pyramid/tests/test_config/test_security.py b/pyramid/tests/test_config/test_security.py
index d05d1d4711..817f6ce02b 100644
--- a/pyramid/tests/test_config/test_security.py
+++ b/pyramid/tests/test_config/test_security.py
@@ -89,3 +89,12 @@ def test_set_default_permission(self):
         self.assertEqual(config.registry.getUtility(IDefaultPermission),
                          'view')
 
+    def test_add_permission(self):
+        config = self._makeOne(autocommit=True)
+        config.add_permission('perm')
+        cat = config.registry.introspector.get_category('permissions')
+        self.assertEqual(len(cat), 1)
+        D = cat[0]
+        intr = D['introspectable']
+        self.assertEqual(intr['value'], 'perm')
+