- Removed API documentation for ``pyramid.testing`` APIs named

  ``registerDummySecurityPolicy``, ``registerResources``, ``registerModels``,
  ``registerEventListener``, ``registerTemplateRenderer``,
  ``registerDummyRenderer``, ``registerView``, ``registerUtility``,
  ``registerAdapter``, ``registerSubscriber``, ``registerRoute``,
  and ``registerSettings``.

- Deprecated-since-BFG-1.2 APIs from ``pyramid.testing`` now properly emit
  deprecation warnings.

4 files changed, 114 insertions, 43 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index c2922f591..607114d84 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -7,6 +7,19 @@ Documentation
 - Fixed bug in ZODB Wiki tutorial (missing dependency on ``docutils`` in
   "models" step within ``setup.py``).
 
+- Removed API documentation for ``pyramid.testing`` APIs named
+  ``registerDummySecurityPolicy``, ``registerResources``, ``registerModels``,
+  ``registerEventListener``, ``registerTemplateRenderer``,
+  ``registerDummyRenderer``, ``registerView``, ``registerUtility``,
+  ``registerAdapter``, ``registerSubscriber``, ``registerRoute``,
+  and ``registerSettings``.
+
+Bug Fixes
+---------
+
+- Deprecated-since-BFG-1.2 APIs from ``pyramid.testing`` now properly emit
+  deprecation warnings.
+
 1.0b3 (2011-01-28)
 ==================
 
diff --git a/docs/api/testing.rst b/docs/api/testing.rst
index fdcdadee8..f388dc263 100644
--- a/docs/api/testing.rst
+++ b/docs/api/testing.rst
@@ -5,26 +5,6 @@
 
 .. automodule:: pyramid.testing
 
-  .. autofunction:: registerDummySecurityPolicy
-
-  .. autofunction:: registerResources
-
-  .. autofunction:: registerEventListener
-
-  .. autofunction:: registerTemplateRenderer
-
-  .. autofunction:: registerView
-
-  .. autofunction:: registerUtility
-
-  .. autofunction:: registerAdapter
-
-  .. autofunction:: registerSubscriber
-
-  .. autofunction:: registerRoute
-
-  .. autofunction:: registerSettings
-
   .. autofunction:: setUp
 
   .. autofunction:: tearDown
diff --git a/pyramid/testing.py b/pyramid/testing.py
index f159d47f8..096b260b2 100644
--- a/pyramid/testing.py
+++ b/pyramid/testing.py
@@ -2,6 +2,7 @@ import copy
 import os
 
 from zope.configuration.xmlconfig import _clearContext
+from zope.deprecation import deprecated
 
 from zope.interface import implements
 from zope.interface import Interface
@@ -64,6 +65,12 @@ def registerDummySecurityPolicy(userid=None, groupids=(), permissive=True):
     config.commit()
     return result
 
+deprecated('registerDummySecurityPolicy',
+           'The testing.registerDummySecurityPolicy API is deprecated as of '
+           'Pyramid 1.0. Instead use the'
+           'pyramid.config.Configurator.testing_securitypolicy '
+           'method in your unit and integration tests. ')
+
 def registerResources(resources):
     """ Registers a dictionary of :term:`resource` objects that can be
     resolved via the :func:`pyramid.traversal.find_resource` API.
@@ -90,8 +97,20 @@ def registerResources(resources):
     config.commit()
     return result
 
+deprecated('registerResources',
+           'The testing.registerResources API is deprecated as of '
+           'Pyramid 1.0. Instead use the'
+           'pyramid.config.Configurator.testing_resources '
+           'method in your unit and integration tests. ')
+
 registerModels = registerResources
 
+deprecated('registerModels',
+           'The testing.registerModels API is deprecated as of '
+           'Pyramid 1.0. Instead use the'
+           'pyramid.config.Configurator.testing_resources '
+           'method in your unit and integration tests. ')
+
 def registerEventListener(event_iface=None):
     """ Registers an :term:`event` listener (aka :term:`subscriber`)
     listening for events of the type ``event_iface``.  This method
@@ -120,6 +139,12 @@ def registerEventListener(event_iface=None):
     config.commit()
     return result
 
+deprecated('registerEventListener',
+           'The testing.registerEventListener API is deprecated as of '
+           'Pyramid 1.0. Instead use the'
+           'pyramid.config.Configurator.testing_add_subscriber '
+           'method in your unit and integration tests. ')
+
 def registerTemplateRenderer(path, renderer=None):
     """ Register a template renderer at ``path`` (usually a relative
     filename ala ``templates/foo.pt``) and return the renderer object.
@@ -132,7 +157,7 @@ def registerTemplateRenderer(path, renderer=None):
 
     .. warning:: This API is deprecated as of :app:`Pyramid` 1.0.
        Instead use the
-       :meth:`pyramid.config.Configurator.testing_add_template`
+       :meth:`pyramid.config.Configurator.testing_add_renderer`
        method in your unit and integration tests.
 
     """
@@ -142,10 +167,22 @@ def registerTemplateRenderer(path, renderer=None):
     config.commit()
     return result
 
+deprecated('registerTemplateRenderer',
+           'The testing.registerTemplateRenderer API is deprecated as of '
+           'Pyramid 1.0. Instead use the'
+           'pyramid.config.Configurator.testing_add_renderer '
+           'method in your unit and integration tests. ')
+
 # registerDummyRenderer is a deprecated alias that should never be removed
 # (too much usage in the wild)
 registerDummyRenderer = registerTemplateRenderer
 
+deprecated('registerDummyRenderer',
+           'The testing.registerDummyRenderer API is deprecated as of '
+           'Pyramid 1.0. Instead use the'
+           'pyramid.config.Configurator.testing_add_renderer '
+           'method in your unit and integration tests. ')
+
 def registerView(name, result='', view=None, for_=(Interface, Interface),
                  permission=None):
     """ Registers a :app:`Pyramid` :term:`view callable` under the
@@ -187,6 +224,12 @@ def registerView(name, result='', view=None, for_=(Interface, Interface),
         _secure.__permitted__ = permitted
         return registerAdapter(_secure, for_, ISecuredView, name)
 
+deprecated('registerView',
+           'The registerView API is deprecated as of '
+           'Pyramid 1.0. Instead use the'
+           'pyramid.config.Configurator.add_view '
+           'method in your unit and integration tests. ')
+
 def registerUtility(impl, iface=Interface, name=''):
     """ Register a ZCA utility component.
 
@@ -210,6 +253,13 @@ def registerUtility(impl, iface=Interface, name=''):
     reg.registerUtility(impl, iface, name=name)
     return impl
 
+deprecated('registerUtility',
+           'The registerUtility API is deprecated as of '
+           'Pyramid 1.0. Instead use the'
+           'pyramid.registry.registerUtility method (via '
+           'e.g. "config.registry.registerUtility(..)" '
+           'method in your unit and integration tests. ')
+
 def registerAdapter(impl, for_=Interface, provides=Interface, name=''):
     """ Register a ZCA adapter component.
 
@@ -242,6 +292,13 @@ def registerAdapter(impl, for_=Interface, provides=Interface, name=''):
     reg.registerAdapter(impl, for_, provides, name=name)
     return impl
 
+deprecated('registerAdapter',
+           'The registerAdapter API is deprecated as of '
+           'Pyramid 1.0. Instead use the'
+           'pyramid.registry.registerAdapter method (via '
+           'e.g. "config.registry.registerAdapter(..)" '
+           'method in your unit and integration tests. ')
+
 def registerSubscriber(subscriber, iface=Interface):
     """ Register a ZCA subscriber component.
 
@@ -268,6 +325,12 @@ def registerSubscriber(subscriber, iface=Interface):
     config.commit()
     return result
 
+deprecated('registerSubscriber',
+           'The testing.registerSubscriber API is deprecated as of '
+           'Pyramid 1.0. Instead use the'
+           'pyramid.config.Configurator.add_subscriber '
+           'method in your unit and integration tests. ')
+
 def registerRoute(pattern, name, factory=None):
     """ Register a new :term:`route` using a pattern
     (e.g. ``:pagename``), a name (e.g. ``home``), and an optional root
@@ -291,6 +354,12 @@ def registerRoute(pattern, name, factory=None):
     config.commit()
     return result
 
+deprecated('registerRoute',
+           'The testing.registerRoute API is deprecated as of '
+           'Pyramid 1.0. Instead use the'
+           'pyramid.config.Configurator.add_route '
+           'method in your unit and integration tests. ')
+
 def registerSettings(dictarg=None, **kw):
     """Register one or more 'setting' key/value pairs.  A setting is
     a single key/value pair in the dictionary-ish object returned from
@@ -317,6 +386,12 @@ def registerSettings(dictarg=None, **kw):
     config = Configurator(registry=registry)
     config.add_settings(dictarg, **kw)
 
+deprecated('registerSettings',
+           'The testing.registerSettings API is deprecated as of '
+           'Pyramid 1.0. Instead use the'
+           'pyramid.config.Configurator.add_settings '
+           'method in your unit and integration tests. ')
+
 class DummyRootFactory(object):
     __parent__ = None
     __name__ = None
@@ -360,12 +435,11 @@ class DummySecurityPolicy(object):
 class DummyTemplateRenderer(object):
     """
     An instance of this class is returned from
-    :func:`pyramid.testing.registerTemplateRenderer`.  It has a
+    :meth:`pyramid.config.Configurator.testing_add_renderer`.  It has a
     helper function (``assert_``) that makes it possible to make an
     assertion which compares data passed to the renderer by the view
     function against expected key/value pairs.
     """
-
     def __init__(self, string_response=''):
         self._received = {}
         self._string_response = string_response
@@ -622,21 +696,17 @@ def setUp(registry=None, request=None, hook_zca=True, autocommit=True,
     Use this function in the ``setUp`` method of a unittest test case
     which directly or indirectly uses:
 
-    - any of the ``register*`` functions in :mod:`pyramid.testing`
-      (such as :func:`pyramid.testing.registerResources`)
-
     - any method of the :class:`pyramid.config.Configurator`
       object returned by this function.
 
     - the :func:`pyramid.threadlocal.get_current_registry` or
       :func:`pyramid.threadlocal.get_current_request` functions.
 
-    If you use the ``testing.register*`` APIs, or the
-    ``get_current_*`` functions (or call :app:`Pyramid` code that
-    uses these functions) without calling ``setUp``,
-    :func:`pyramid.threadlocal.get_current_registry` will return a
-    *global* :term:`application registry`, which may cause unit tests
-    to not be isolated with respect to registrations they perform.
+    If you use the ``get_current_*`` functions (or call :app:`Pyramid` code
+    that uses these functions) without calling ``setUp``,
+    :func:`pyramid.threadlocal.get_current_registry` will return a *global*
+    :term:`application registry`, which may cause unit tests to not be
+    isolated with respect to registrations they perform.
 
     If the ``registry`` argument is ``None``, a new empty
     :term:`application registry` will be created (an instance of the
@@ -744,7 +814,7 @@ def cleanUp(*arg, **kw):
 
 class DummyRendererFactory(object):
     """ Registered by
-    ``pyramid.config.Configurator.testing_add_renderer`` as
+    :meth:`pyramid.config.Configurator.testing_add_renderer` as
     a dummy renderer factory.  The indecision about what to use as a
     key (a spec vs. a relative name) is caused by test suites in the
     wild believing they can register either.  The ``factory`` argument
diff --git a/pyramid/tests/test_renderers.py b/pyramid/tests/test_renderers.py
index 8711c25e0..3edeb0f4c 100644
--- a/pyramid/tests/test_renderers.py
+++ b/pyramid/tests/test_renderers.py
@@ -17,7 +17,8 @@ class TestTemplateRendererFactory(unittest.TestCase):
     def test_abspath_notfound(self):
         from pyramid.interfaces import ITemplateRenderer
         abspath = '/wont/exist'
-        testing.registerUtility({}, ITemplateRenderer, name=abspath)
+        self.config.registry.registerUtility(
+            {}, ITemplateRenderer, name=abspath)
         info = DummyRendererInfo({
             'name':abspath,
             'package':None,
@@ -32,7 +33,8 @@ class TestTemplateRendererFactory(unittest.TestCase):
         import os
         abspath = os.path.abspath(__file__)
         renderer = {}
-        testing.registerUtility(renderer, ITemplateRenderer, name=abspath)
+        self.config.registry.registerUtility(
+            renderer, ITemplateRenderer, name=abspath)
         info = DummyRendererInfo({
             'name':abspath,
             'package':None,
@@ -48,7 +50,8 @@ class TestTemplateRendererFactory(unittest.TestCase):
         import os
         abspath = os.path.abspath(__file__)
         renderer = {}
-        testing.registerUtility(renderer, ITemplateRenderer, name=abspath)
+        self.config.registry.registerUtility(
+            renderer, ITemplateRenderer, name=abspath)
         info = DummyRendererInfo({
             'name':abspath,
             'package':None,
@@ -62,7 +65,8 @@ class TestTemplateRendererFactory(unittest.TestCase):
     def test_relpath_path_registered(self):
         renderer = {}
         from pyramid.interfaces import ITemplateRenderer
-        testing.registerUtility(renderer, ITemplateRenderer, name='foo/bar')
+        self.config.registry.registerUtility(
+            renderer, ITemplateRenderer, name='foo/bar')
         spec = 'foo/bar'
         info = DummyRendererInfo({
             'name':spec,
@@ -79,8 +83,9 @@ class TestTemplateRendererFactory(unittest.TestCase):
         from pyramid.interfaces import ITemplateRenderer
         import pyramid.tests
         spec = 'bar/baz'
-        testing.registerUtility(renderer, ITemplateRenderer,
-                                name='pyramid.tests:bar/baz')
+        self.config.registry.registerUtility(
+            renderer, ITemplateRenderer,
+            name='pyramid.tests:bar/baz')
         info = DummyRendererInfo({
             'name':spec,
             'package':pyramid.tests,
@@ -116,7 +121,8 @@ class TestTemplateRendererFactory(unittest.TestCase):
             'type':'type',
             })
         renderer = {}
-        testing.registerUtility(renderer, ITemplateRenderer, name=spec)
+        self.config.registry.registerUtility(
+            renderer, ITemplateRenderer, name=spec)
         result = self._callFUT(info, None)
         self.failUnless(result is renderer)
 
@@ -148,7 +154,7 @@ class TestTemplateRendererFactory(unittest.TestCase):
         from pyramid.interfaces import ISettings
         from pyramid.interfaces import ITemplateRenderer
         settings = {'reload_assets':True}
-        testing.registerUtility(settings, ISettings)
+        self.config.registry.registerUtility(settings, ISettings)
         renderer = {}
         factory = DummyFactory(renderer)
         spec = 'test_renderers.py'
@@ -208,7 +214,8 @@ class TestRendererFromName(unittest.TestCase):
         fixture = os.path.join(here, 'fixtures/minimal.pt')
         def factory(info, **kw):
             return info
-        testing.registerUtility(factory, IRendererFactory, name='.pt')
+        self.config.registry.registerUtility(
+            factory, IRendererFactory, name='.pt')
         result = self._callFUT(fixture)
         self.assertEqual(result.registry, registry)
         self.assertEqual(result.type, '.pt')
@@ -227,7 +234,8 @@ class TestRendererFromName(unittest.TestCase):
         fixture = os.path.join(here, 'fixtures/minimal.pt')
         def factory(info, **kw):
             return info
-        testing.registerUtility(factory, IRendererFactory, name='.pt')
+        self.config.registry.registerUtility(
+            factory, IRendererFactory, name='.pt')
         result = self._callFUT(fixture, pyramid)
         self.assertEqual(result.registry, registry)
         self.assertEqual(result.type, '.pt')