Features

--------

- The ``scan`` method of a ``Configurator`` can be passed an ``ignore``
  argument, which can be a string, a callable, or a list consisting of
  strings and/or callables.  This feature allows submodules, subpackages, and
  global objects from being scanned.  See
  http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for
  more information about how to use the ``ignore`` argument to ``scan``.

Dependencies
------------

- Depend on ``venusian`` >= 1.0a3 to provide scan ``ignore`` support.

6 files changed, 70 insertions, 3 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index d76f7087a..fcd54217f 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -1,3 +1,21 @@
+Next release
+============
+
+Features
+--------
+
+- The ``scan`` method of a ``Configurator`` can be passed an ``ignore``
+  argument, which can be a string, a callable, or a list consisting of
+  strings and/or callables.  This feature allows submodules, subpackages, and
+  global objects from being scanned.  See
+  http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for
+  more information about how to use the ``ignore`` argument to ``scan``.
+
+Dependencies
+------------
+
+- Depend on ``venusian`` >= 1.0a3 to provide scan ``ignore`` support.
+
 1.3a7 (2012-02-07)
 ==================
 
diff --git a/docs/whatsnew-1.3.rst b/docs/whatsnew-1.3.rst
index 231421262..b6cfde039 100644
--- a/docs/whatsnew-1.3.rst
+++ b/docs/whatsnew-1.3.rst
@@ -252,6 +252,13 @@ Minor Feature Additions
   http://www.python.org/dev/peps/pep-0333/#optional-platform-specific-file-handling)
   when one is provided by the web server.
 
+- The :meth:`pyramid.config.Configurator.scan` method can be passed an
+  ``ignore`` argument, which can be a string, a callable, or a list
+  consisting of strings and/or callables.  This feature allows submodules,
+  subpackages, and global objects from being scanned.  See
+  http://readthedocs.org/docs/venusian/en/latest/#ignore-scan-argument for
+  more information about how to use the ``ignore`` argument to ``scan``.
+
 Backwards Incompatibilities
 ---------------------------
 
diff --git a/pyramid/config/__init__.py b/pyramid/config/__init__.py
index bd3a80ad3..1656b5410 100644
--- a/pyramid/config/__init__.py
+++ b/pyramid/config/__init__.py
@@ -851,7 +851,8 @@ class Configurator(
         return self.manager.pop()
 
     # this is *not* an action method (uses caller_package)
-    def scan(self, package=None, categories=None, onerror=None, **kw):
+    def scan(self, package=None, categories=None, onerror=None, ignore=None,
+             **kw):
         """Scan a Python package and any of its subpackages for objects
         marked with :term:`configuration decoration` such as
         :class:`pyramid.view.view_config`.  Any decorated object found will
@@ -879,6 +880,20 @@ class Configurator(
         :term:`Venusian` documentation for more information about ``onerror``
         callbacks.
 
+        The ``ignore`` argument, if provided, should be a Venusian ``ignore``
+        value.  Providing an ``ignore`` argument allows the scan to ignore
+        particular modules, packages, or global objects during a scan.
+        ``ignore`` can be a string or a callable, or a list containing
+        strings or callables.  The simplest usage of ``ignore`` is to provide
+        a module or package by providing a full path to its dotted name.  For
+        example: ``config.scan(ignore='my.module.subpackage')`` would ignore
+        the ``my.module.subpackage`` package during a scan, which would
+        prevent the subpackage and any of its submodules from being imported
+        and scanned.  See the :term:`Venusian` documentation for more
+        information about the ``ignore`` argument.
+
+        .. note:: the ``ignore`` argument is new in Pyramid 1.3.
+        
         To perform a ``scan``, Pyramid creates a Venusian ``Scanner`` object.
         The ``kw`` argument represents a set of keyword arguments to pass to
         the Venusian ``Scanner`` object's constructor.  See the
@@ -900,7 +915,9 @@ class Configurator(
         ctorkw.update(kw)
 
         scanner = self.venusian.Scanner(**ctorkw)
-        scanner.scan(package, categories=categories, onerror=onerror)
+        
+        scanner.scan(package, categories=categories, onerror=onerror,
+                     ignore=ignore)
 
     def make_wsgi_app(self):
         """ Commits any pending configuration statements, sends a
diff --git a/pyramid/tests/test_config/test_init.py b/pyramid/tests/test_config/test_init.py
index a866bed55..d237b3fe8 100644
--- a/pyramid/tests/test_config/test_init.py
+++ b/pyramid/tests/test_config/test_init.py
@@ -929,6 +929,28 @@ pyramid.tests.test_config.dummy_include2""",
         result = render_view_to_response(ctx, req, 'pod_notinit')
         self.assertEqual(result, None)
 
+    def test_scan_integration_with_ignore(self):
+        from zope.interface import alsoProvides
+        from pyramid.interfaces import IRequest
+        from pyramid.view import render_view_to_response
+        import pyramid.tests.test_config.pkgs.scannable as package
+        config = self._makeOne(autocommit=True)
+        config.scan(package, 
+                    ignore='pyramid.tests.test_config.pkgs.scannable.another')
+
+        ctx = DummyContext()
+        req = DummyRequest()
+        alsoProvides(req, IRequest)
+        req.registry = config.registry
+
+        req.method = 'GET'
+        result = render_view_to_response(ctx, req, '')
+        self.assertEqual(result, 'grokked')
+
+        # ignored
+        v = render_view_to_response(ctx, req, 'another_stacked_class2')
+        self.assertEqual(v, None)
+        
     def test_scan_integration_dottedname_package(self):
         from zope.interface import alsoProvides
         from pyramid.interfaces import IRequest
diff --git a/setup.py b/setup.py
index c719bd9fe..a6cfa1480 100644
--- a/setup.py
+++ b/setup.py
@@ -37,7 +37,7 @@ install_requires=[
     'repoze.lru >= 0.4', # py3 compat
     'zope.interface >= 3.8.0',  # has zope.interface.registry
     'zope.deprecation >= 3.5.0', # py3 compat
-    'venusian >= 1.0a1', # ``onerror``
+    'venusian >= 1.0a3', # ``ignore``
     'translationstring >= 0.4', # py3 compat
     'PasteDeploy >= 1.5.0', # py3 compat
     ]
diff --git a/tox.ini b/tox.ini
index 79728bc18..1e7223886 100644
--- a/tox.ini
+++ b/tox.ini
@@ -11,6 +11,7 @@ deps =
     repoze.sphinx.autointerface
     WebTest
     virtualenv
+    venusian>=1.0a3
 
 [testenv:py32]
 commands = 
@@ -18,6 +19,7 @@ commands =
 deps =
     WebTest
     virtualenv
+    venusian>=1.0a3
 
 [testenv:cover]
 basepython =
@@ -30,6 +32,7 @@ deps =
     WebTest
     repoze.sphinx.autointerface
     virtualenv
+    venusian>=1.0a3
     nose
     coverage==3.4
     nosexcover