From b40fb8b26fe37102b076cd2310ea7a3fe8b79311 Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@plope.com>
Date: Sat, 3 Dec 2011 21:04:24 -0500
Subject: add a noop introspector (allow introspection to be turned off)

---
 TODO.txt                       |  2 --
 docs/api/registry.rst          |  5 +++++
 docs/narr/introspector.rst     | 20 ++++++++++++++++--
 pyramid/registry.py            | 22 ++++++++++++++++++++
 pyramid/tests/test_registry.py | 46 ++++++++++++++++++++++++++++++++++++++++++
 5 files changed, 91 insertions(+), 4 deletions(-)

diff --git a/TODO.txt b/TODO.txt
index 0a15d8db0..4692b073b 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -23,8 +23,6 @@ Must-Have
 
   * introspection hiding for directives?
 
-  * make it possible to disuse introspection?
-
 - Give discriminators a nicer repr for conflict reporting?
 
 Nice-to-Have
diff --git a/docs/api/registry.rst b/docs/api/registry.rst
index 3dbf73a67..25192f3ed 100644
--- a/docs/api/registry.rst
+++ b/docs/api/registry.rst
@@ -38,4 +38,9 @@
 
    This class is new as of :app:`Pyramid` 1.3.
 
+.. class:: noop_introspector
+
+   An introspector which throws away all registrations, useful for disabling
+   introspection altogether (pass as ``introspector`` to the
+   :term:`Configurator` constructor).
 
diff --git a/docs/narr/introspector.rst b/docs/narr/introspector.rst
index ac0859164..71b41773c 100644
--- a/docs/narr/introspector.rst
+++ b/docs/narr/introspector.rst
@@ -512,8 +512,8 @@ introspectables in categories not described here.
 
      The ``over`` argument passed to ``add_tween`` (a string).
 
-Toolbar Introspection
----------------------
+Introspection in the Toolbar
+----------------------------
 
 The Pyramid debug toolbar (part of the ``pyramid_debugtoolbar`` package)
 provides a canned view of all registered introspectables and their
@@ -521,4 +521,20 @@ relationships.  It looks something like this:
 
 .. image:: tb_introspector.png
 
+Disabling Introspection
+-----------------------
 
+You can disable Pyramid introspection by passing the object
+:attr:`pyramid.registry.noop_introspector` to the :term:`Configurator`
+constructor in your application setup:
+
+.. code-block:: python
+
+   from pyramid.config import Configurator
+   from pyramid.registry import noop_introspector
+   config = Configurator(..., introspector=noop_introspector)
+
+When the noop introspector is active, all introspectables generated by the
+framework are thrown away.  A noop introspector behaves just like a "real"
+introspector, but the methods of a noop introspector do nothing and return
+null values.
diff --git a/pyramid/registry.py b/pyramid/registry.py
index 295d6c6b9..d594ae910 100644
--- a/pyramid/registry.py
+++ b/pyramid/registry.py
@@ -172,6 +172,28 @@ class Introspector(object):
             raise KeyError((category_name, discriminator))
         return self._refs.get(intr, [])
 
+@implementer(IIntrospector)
+class _NoopIntrospector(object):
+    def add(self, intr):
+        pass
+    def get(self, category_name, discriminator, default=None):
+        return default
+    def get_category(self, category_name, default=None, sort_key=None):
+        return default
+    def categorized(self, sort_key=None):
+        return []
+    def categories(self):
+        return []
+    def remove(self, category_name, discriminator):
+        return
+    def relate(self, *pairs):
+        return
+    unrelate = relate
+    def related(self, intr):
+        return []
+
+noop_introspector = _NoopIntrospector()
+
 @implementer(IIntrospectable)
 class Introspectable(dict):
 
diff --git a/pyramid/tests/test_registry.py b/pyramid/tests/test_registry.py
index 11019b852..29803346a 100644
--- a/pyramid/tests/test_registry.py
+++ b/pyramid/tests/test_registry.py
@@ -254,6 +254,52 @@ class TestIntrospector(unittest.TestCase):
         del inst._categories['category']
         self.assertRaises(KeyError, inst.related, intr)
 
+class Test_noop_introspector(unittest.TestCase):
+    def _makeOne(self):
+        from pyramid.registry import noop_introspector
+        return noop_introspector
+
+    def test_conformance(self):
+        from zope.interface.verify import verifyObject
+        from pyramid.interfaces import IIntrospector
+        verifyObject(IIntrospector, self._makeOne())
+
+    def test_add(self):
+        inst = self._makeOne()
+        self.assertEqual(inst.add('a'), None)
+
+    def test_get(self):
+        inst = self._makeOne()
+        self.assertEqual(inst.get('category', 'd', default='123'), '123')
+
+    def test_get_category(self):
+        inst = self._makeOne()
+        self.assertEqual(inst.get_category('category', default='123'), '123')
+        
+    def test_categorized(self):
+        inst = self._makeOne()
+        self.assertEqual(inst.categorized(), [])
+
+    def test_categories(self):
+        inst = self._makeOne()
+        self.assertEqual(inst.categories(), [])
+        
+    def test_remove(self):
+        inst = self._makeOne()
+        self.assertEqual(inst.remove('cat', 'discrim'), None)
+
+    def test_relate(self):
+        inst = self._makeOne()
+        self.assertEqual(inst.relate(), None)
+
+    def test_unrelate(self):
+        inst = self._makeOne()
+        self.assertEqual(inst.unrelate(), None)
+
+    def test_related(self):
+        inst = self._makeOne()
+        self.assertEqual(inst.related('a'), [])
+
 class TestIntrospectable(unittest.TestCase):
     def _getTargetClass(slf):
         from pyramid.registry import Introspectable
-- 
cgit v1.2.3